erpc-cli is developed and maintained by ELSOUL LABO B.V. (Netherlands), the
operator of the ERPC service.
Please report vulnerabilities privately through GitHub private vulnerability reporting. Do not open a public issue for security problems.
Include the affected version (erpc version --json), the platform, steps to
reproduce, and the impact you observed. Encrypted reports are not required.
We acknowledge reports within 5 business days and aim to publish a fix or a mitigation within 90 days of confirmation. We follow coordinated disclosure: we will agree a publication date with you and credit you in the advisory unless you prefer otherwise.
Only the latest release receives security fixes. Every release so far is a pre-release.
In scope: the erpc binary and the crates in this repository, the installer
script served at install.erpc.global, the release artifacts and their
signatures.
Out of scope: the ERPC backend services (report those through the ERPC
dashboard support channel), third-party node clients that erpc installs on
your servers, and issues that require physical access to an operator machine.
Every release ships a signed release-manifest.json (minisign), a CycloneDX
SBOM and GitHub build provenance attestations. See docs/verify-release.md.
On the operator's machine erpc keeps these secrets:
- the session for your ERPC account, an access token and a refresh token obtained through the OAuth device authorization grant, in the store described below;
- the storage and backup secrets listed under the storage section below, in the
same store, and a machine's own backup keys in
~/.erpc/backup.env; - an
erpc workerapp's trading key and secret settings, in 1Password, the keychain or, on a machine with neither, the worker keystore described below.
Node keys that erpc holds for you, and the erpc wallet key, are made or read in
memory and stored in 1Password; docs/nodes.md lists the keys that stay on node
hosts instead. One command writes them to disk: erpc validator vote-account writes
the identity and vote keys to 0600 files under the state directory while the
Solana CLI runs, and wipes them afterwards. A process that dies can leave a file
until a later run sweeps it. Adding a restic key also keeps its password in a
temporary file in the configuration directory while restic runs, and a process that dies can leave that file behind.
When it uses a 1Password
service account, it reads OP_SERVICE_ACCOUNT_TOKEN from its environment and
passes it to the op processes it starts, and to no other process: the
browser erpc login opens is started without any variable whose name begins
with OP_, in any case. It does not write that token anywhere. A session the
operator opened with op signin, on a machine without the 1Password app, is
handled the same way: its OP_SESSION_<account> variable goes to op and
nowhere else.
The session is kept in one store. erpc login at a terminal asks which: the
operating system's keychain, which is the default, or 1Password when it
answers -- the desktop app, or without it an op signin session that op whoami accepts -- followed by which vault. --store (and
--vault) choose without asking. The choice is recorded as credential_store
(and credential_vault) in config.toml beside the state directory, and the
other commands use it.
Without a choice, given or recorded, the store is the first of these that applies:
- a 1Password service account, when
OP_SERVICE_ACCOUNT_TOKENis set; - the operating system's keychain, when there is one;
- a file in the erpc state directory.
erpc doctor reports which store is in use and why.
On Linux the keychain is the Secret Service where one answers on the session
bus, and otherwise the kernel's persistent keyring for the user: in memory,
never on disk, kept across logins until a reboot or a few days unused, after
which erpc login is asked for again. The kernel lets a process use that
keyring only when it holds one of the user's keyrings, which a login gives
it; a process started without one (su without -, sudo -E) is refused
and told so.
On macOS the keychain is reached through Apple's /usr/bin/security, not
the keychain API directly. An erpc built on the operator's machine has no
lasting code signature, so an item it made itself asked for the login
password on every read and write. The item therefore trusts security, and
with it any other program running as the same user, which can read the
session by running security too; this is the trade other command-line
tools make. The keychain still keeps the session encrypted at rest and away
from other users, which the file store cannot (crates/erpc-auth/src/store/security_cli.rs).
The 1Password item is titled with the machine's name, so that two machines
never share, and keep rotating, one session. ERPC_HOST_LABEL overrides the
name.
The erpc state directory is $ERPC_HOME/state or, without ERPC_HOME,
.erpc/state in your home directory. erpc will not use a state directory
that is not an absolute path.
erpc writes a session to that directory in the following cases, and
erpc doctor reports each file for as long as it exists:
- The file store.
erpc loginwarns when the session is going there. If the file cannot be parsed, nothing in it can be read:erpc loginreplaces it anderpc logoutremoves it, as a whole, anderpc loginsays so. - A parked session. If the issuer has rotated a refresh token and the
new one cannot reach the store, it is written here so that it is not lost.
That happens when the store refuses it; when
erpcis asked to stop (Ctrl-C, and on Unix also SIGTERM and the terminal closing) and the store has not taken it within ten seconds, or a second request to stop comes first; and whenerpcpanics before the store has it. A save that lands after all leaves a copy of what the store already holds, which the next command removes. The next command that reads the session, such aserpc whoami, moves it into the store if the store still holds the session it replaced.erpc loginanderpc logoutrevoke it and remove it, and say so when they could not. - An interrupted write. The two files above are written to a temporary file first and then renamed into place. A crash between the two steps leaves that temporary file behind.
On Unix these files are created with mode 0600. On Windows erpc sets no
permissions of its own, so the files have the permissions of the directory
they are in.
- The access token is sent as a bearer token only to the hosts listed for its
audience in
crates/erpc-auth/src/allowlist.rs. - The refresh token is sent only to its issuer's token and revoke endpoints, checked against the issuer's host before each request.
- Every request URL's host is a compile-time constant, and so is its path
up to the one value a path may carry: a storage access key id, an
integer, or a gasless session id, checked to be a UUID before the URL is
built. Query values are percent-encoded. On the account routes they are
a region, a bare metal category, a page cursor or a product id, and are
letters, digits,
-and_only, checked before the request is sent;erpc storagesends the file path or prefix the operator named, encoded. - The HTTP client is configured to accept
httpsonly and not to follow redirects. Neither setting is covered by a test; the reasons are given beside them incrates/erpc-auth/src/client.rs.
erpc storage putencrypts files with an account key before they leave the machine;docs/storage-encryption.mddescribes the format. With the file store that key sits in~/.erpc/storage-key(0600), not encrypted, and the backup secrets below are not encrypted either.erpc backupkeeps the restic repository's master password and aread_writestorage access key in the storeerpc loginchose. Each machine gets its ownappend_onlyaccess key and its own restic key, kept in~/.erpc/backup.env(0600).docs/backup.mdsets out who holds what. Theappend_onlykey keeps a machine from deleting backups only where the machine holds neither the erpc session nor the account's backup secrets, which the machineerpc backup initran on does;docs/backup.mdexplains ("What the append-only key protects, and when").- A storage access key is sent only by the restic that
erpc backupruns, as Basic authentication, to user-api's/v3/storage/restic. restic gets it, and the repository password, from its environment, never from its command line or a URL, and runs with an otherwise cleared environment. - The restic program is a pinned version. Both the release archive and the program inside it are checked against SHA-256 digests compiled into erpc, and a newer digest is never read from the network.
erpc worker key new, key import and secret put keep an app's trading
key and secret settings in 1Password or the operating system's keychain.
Where erpc login does not keep the session in 1Password and the keychain
cannot keep a value past a reboot (Linux with no Secret Service), and
wherever --store keystore asks for it, they write them to disk instead,
encrypted: the keystore, the directory keystore beside config.toml
(~/.erpc/keystore). No key or secret value in it is in cleartext. Its
format is set out at the top of crates/erpc-auth/src/store/keystore.rs,
and docs/worker.md ("The keystore") says how it is used.
-
What is written.
master.json: a random 32-byte master key, sealed with ChaCha20-Poly1305 under a key that PBKDF2-HMAC-SHA256 (600,000 iterations, a random 32-byte salt) derives from a passphrase the operator chooses. One file per value: the value sealed with ChaCha20-Poly1305 under a key that HKDF-SHA256 derives from the master key and a salt of the entry's own, with the entry's name and its kind (a trading key, or a secret) in the associated data. On Unix the directories are created with mode0700and the files with0600; on Windowserpcsets no permissions of its own. Each file is written under a temporary name and renamed into place; a crash between the two steps leaves the temporary file, which holds the same sealed text. -
The passphrase is read from a hidden prompt at a terminal and from nowhere else: not from an argument, an environment variable or a pipe. It is not stored.
erpccannot recover it, or a keystore whose files are lost. On Unix the terminal's echo is held off from the first prompt until the last attempt has been checked, so an attempt typed ahead while one is checked is not shown; what was typed and not read is discarded. -
The unlock. On Linux the unwrapped master key is kept in the kernel's persistent keyring for the user, in memory, so that the passphrase is not asked for by every command. It stays until a reboot, until that keyring has gone unused for the time in
/proc/sys/kernel/keys/persistent_keyring_expiry, or untilerpc worker secret lock, which drops every unlockerpckeeps for the user, whichever keystore it opens. While it is there, any process running as the same user can read it (one whose session does not hold the user's keyring can link it in), and with it open every entry. On other systems nothing is kept, and each command asks. -
What it does not protect against. Someone who has the files and the passphrase. A passphrase that can be guessed: PBKDF2 makes each guess slow, and no more. A process running as the operator while the keystore is unlocked, or one that reads the terminal the passphrase is typed at. The names of the entries and the lengths of their values are not hidden, and an entry replaced by an older copy of itself opens.
-
The trading key's gate is separate.
erpcreads the key that[wallet]names only for a person at a terminal, and not for an AI tool or with a 1Password service account, in whichever store it is kept (crates/erpc-secret/src/gate.rs). An unlocked keystore does not change that. A secret setting is read with no such gate, so a key is kept from being read as one:- In the keystore, each entry is sealed as a trading key or as a secret.
One kept as a key (by
key neworkey import) opens only as the key[wallet]names, and not as a secret, whatever names it; a secret does not open as a key. erpc.tomlis refused when a[secrets]line names the entry[wallet]names, or a keychain or keystore account ending in.wallet(whereerpcfiles a key), anderpc worker bench --urlrefuses such a reference too.- That leaves a key in 1Password, or under a keychain account that does
not end in
.wallet: nothing in such a reference says that it is a key's. Anerpc.tomlwith no[wallet]that names it under[secrets]has it read as a secret, with no gate.
The gate and the kinds are what
erpcdoes; they do not bind other programs. - In the keystore, each entry is sealed as a trading key or as a secret.
One kept as a key (by
-
One spelling of a name. An entry's file is named after its service and account as they are written. Where file names ignore case (the defaults of macOS and Windows)
<app>.WALLET.jsonis the file of<app>.wallet.json, the trading key's. Soerpc worker secret putkeeps no setting calledWALLET, in any case, in the keychain or the keystore,secret rmremoves none, and the keystore reads its directory before every read, write and removal: where it holds another spelling of the name, it does none of them.
Everything a tool returns is sent to the model, through the ERPC AI
gateway, as part of the conversation. The tools are in
crates/erpc-ai/src/tools.rs; besides those below, the assistant reads
ERPC's documentation (read_skill), asks the person to choose
(ask_choice), and keeps notes between conversations (remember,
forget), which refuse anything that looks like a secret.
- Tools that read user-api with the session: the signed-in account's
credit balance and history, card subscriptions, RPC and AI usage and the
services it runs, and what ERPC offers -- the server catalogue, servers in
stock by region, plan prices, hourly products and the health of each
region. Each passes on only the fields it names in
crates/erpc-ai/src/tools.rsandservices.rs: figures, product names, plans, regions, states and dates, and a service endpoint only when it is an ERPC host with no query, fragment or user in it; for each of the account's VPSs, its IP and login user, so the person can ask where it is; for each of its UDP Forwarding lines, its id, where it sends to (thedestination, the user's server and port), the addresses ERPC sends it from (sourceIp,sourceIps) and user-api's last error text for it (lastError), so the person can point it and open their firewall. A UDP Forwarding list user-api refuses is passed on with its refusal, not as a session to sign in again. From these tools, server passwords, IP whitelists, endpoints that carry a key, payment details, Stripe ids and metadata, API keys and the session never reach the model. None calls the/listcatalogues, which open a Stripe checkout session each time they are read. - Tools that act:
start_hourly_product,end_hourly_product,point_udp_line,top_up_credit,create_credit_wallet,secure_vpsandrestrict_sshchange the account, spend credit or EURC, or change a server.point_udp_linesends one of the account's UDP Forwarding lines to a public IPv4 address and port the person confirms (a Premium line is charged from then on); it changes no firewall. Each asks the person first, with the cursor on no, every time; allowing every command (below) does not change that. - A new VPS's address reaches the model.
wait_until_readyreturns the VPS's state and, once it runs, its IP and login user (never its password).secure_vpsreturns the server asuser@ip, its host key fingerprint and the user's own public address;restrict_sshreturns the addresses SSH is allowed from, the user's included. run_commandruns a command on the user's own computer, and what it prints goes to the model, whatever the command: one that only looks and runs without asking (journalctl,docker logs,systemctl statusamong them, so whatever a service logged), one the person said yes to, or any command once the person allowed every command for the conversation. The only thing hidden is the value of eachapi-key=,api_key=,apikey=andtoken=parameter (redactedincrates/erpc-ai/src/commands.rs). A command that prints a key file, a password or a secret under another name hands it to the model. Once every command is allowed, nothing is asked before a command runs, including one that spends money or changes a server when given--yes, until erpc ai ends or a new conversation starts (/new,/clear).
Report any of the following as a vulnerability, through the channel above:
- secret material written to disk in any way not described above;
- secret material in a log, an error message, or other output;
- a token sent anywhere not described above.
Do not infer from this repository which protections are already in force. What the code does today is what the code in this repository does today.