docs/SECURITY_AND_SAFETY.md

Security and Safety

Non-negotiable invariants

Do not change or weaken:

• deterministic LONG, SHORT, and NO_TRADE decisions;
• Datasource 4 authority;
• noTradeGuard;
• Futures verification;
• provider timestamp and freshness checks;
• risk approval;
• Stop Loss and Take Profit rules;
• leverage caps and volatility haircut;
• quantity/sizing logic;
• Paper execution validation;
• Telegram webhook-only isolation;
• single FastAPI application and port 7860 architecture.

Browser trust model

The browser is untrusted for execution. It may display and calculate convenience diagnostics, but the server ignores browser-derived authorization.

Server-side Paper checks include plan reference, symbol/risk identity, expiry, executed flag, direction, DS4 verification, readiness, guard state, risk approval, executable flag, Paper mode, and fresh re-analysis.

Secret handling

Never expose or commit:

HF_TOKEN
HERMES_ADMIN_PASSWORD
FUTURES_API_KEY
FUTURES_API_SECRET
FUTURES_API_PASSPHRASE
OPENROUTER_API_KEY
GOOGLE_API_KEY
TELEGRAM_BOT_TOKEN
TELEGRAM_WEBHOOK_SECRET
TELEGRAM_BOOTSTRAP_SECRET
TELEGRAM_RELAY_SECRET
cookies or Authorization headers

Diagnostics redact keys and text matching authorization, cookie, token, secret, password, or API key patterns. Continue to sanitize new error fields before they reach API responses or UI.

Market-data integrity

• No fabricated production candles, prices, funding, Open Interest, or order-book levels.
• Missing values are null/Unavailable, not zero.
• HTTP success is not data freshness.
• Provider errors in main UI are concise; detailed errors remain sanitized under Technical Diagnostics.
• Binance regional restriction must not be bypassed with raw IP, DNS override, or disabled TLS.

External AI boundary

External AI (Hermes auxiliary task futures_advisory) may return market bias, confidence, summary, supporting points, and warnings. Implementation uses agent.auxiliary_client.async_call_llm with a strict JSON schema (external_ai/advisory_schema.py). It must never modify:

decision
risk approval
noTradeGuard
Entry
Stop Loss
Take Profit
leverage
quantity
execution availability

Bulk scans must not use advisory AI. The dashboard labels this lane Optional AI context (violet / informational); the deterministic engine lane (emerald) remains authoritative.

Telegram boundary

• Webhook secret-token validation is mandatory.
• Request size is bounded.
• Owner bootstrap is one-time, secret-checked, and private-chat only.
• Users are authorized by configured IDs or persisted owner.
• Commands are rate-limited.
• Callback nonces expire and are user-bound.
• Telegram performs analysis only and contains no order path.
• Polling remains disabled.

Development safety

During ordinary development and deployment verification:

• do not call Paper Execute;
• do not run Testnet or Live execution;
• use the read-only audit script;
• use Paper account endpoints only for display verification;
• do not add an execution keyboard shortcut;
• do not allow a UI feature to write plan or risk state directly.

Review checklist for security-sensitive changes

• Does the change alter a deterministic threshold or formula?
• Can fallback data override DS4 safety?
• Can a missing timestamp be treated as fresh?
• Can the browser enable execution without server state?
• Can a raw error include a secret?
• Can a Telegram request bypass authorization or webhook validation?
• Does the change introduce a second network service or port?
• Does it add an exchange credential requirement?
• Are failure states blocked by default?