Skip to content
Browse the docs

Security

The client is a thin consumer of the Stoa Markets API. Every rule the web application enforces applies unchanged: an active registration, second factor, roles and permissions, and the binding acknowledgement before a request is sent.

Credentials

  • Session tokens are stored in the operating system keychain (macOS Keychain, Windows Credential Manager, or a Secret Service provider on Linux) and nowhere else. Without a keychain the client does not store a session.
  • Your password is read by a hidden prompt and never stored. The second factor is a one-time code.
  • There are no long-lived API keys. Sessions expire; sign in again when prompted.

Scoped sessions

Every command needs a signed-in session. The session stoa login receives is limited on the server to the operations the client offers: reading the catalog, composing and reading requests, and managing the session itself. Accepting a quote, cancelling a request, submitting a quote, settlement and account changes stay in the web application.

Transport

The client talks only to markets.stoaexchange.com over HTTPS.

Writes

  • Every create carries an idempotency key. Re-sending with the same key returns the existing request; the venue never opens a second one.
  • A create on the production venue prints the full composition and the binding statement (on stderr under --json), and asks a person to type the confirmation. --agree-binding-statement exists for a person who has already read a dry run; the statement is still printed. With nobody at a terminal the create stops with the error code AGREEMENT_REQUIRED.
  • A create that fails after it was sent prints the exact command that repeats it with the same idempotency key, so a retry can never open a second request.

Distribution

Install only from PyPI: uv tool install stoa-cli or pipx install stoa-cli.

Reporting a problem

Email [email protected] with a description, the affected command, steps to reproduce, and any proof of concept. The vulnerability disclosure page states the ground rules; the machine-readable version is at /.well-known/security.txt.