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:

```text
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:

```text
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?