[Secrets & Network Security]

Security is the most critical component of the Hoox trading platform. When deploying automated execution scripts, your capital and API credentials must be protected against malicious exploits, unauthorized webhook payloads, and network interceptions.

This guide outlines our Zero Trust security architecture, encrypted secret management procedures (including sync modes), and edge-level firewall protection runbooks. Prefer hoox secrets over manual wrangler secret put for day-to-day ops.

---

🛡️ 1. Zero Trust Network Isolation

Traditional trading systems expose database and exchange execution APIs to the public internet (secured by simple HTTP headers or ports). This creates an active attack surface.

Hoox implements a strict Zero Trust microservice isolation topology:

[Public Internet] ───► [Cloudflare® WAF / Firewall]
                                │
                        (IP & Auth Checks)
                                │
                                ▼
                       [Gateway (hoox)] (Publicly Accessible Node)
                                │
               ┌────────────────┴────────────────┐
               │ V8 Isolate Service Bindings     │
               │ (Private, Encrypted, Zero-TCP)  │
               └────────────────┬────────────────┘
                                │
              ┌─────────────────┼─────────────────┐
              ▼                 ▼                 ▼
       [trade-worker]      [d1-worker]      [agent-worker]
       (No Public URL)   (No Public URL)   (No Public URL)
              │                 │                 │
     (Exchange Orders)   (SQLite Queries)   (AI Risk Audits)

• No Public Endpoints: The trade-worker, d1-worker, and agent-worker literally do not exist on the public internet. They have no public IP addresses or URLs.
• V8 Service Bindings: Communication between the public gateway (hoox) and internal compute nodes is routed entirely inside Cloudflare®'s secure V8 engine isolates. Your trade routing data, database queries, and private logs never travel over the public internet, eliminating TLS decryption and packet-sniffing risks.

---

🔑 2. Encrypted Secret Management via CLI

API keys, exchange secrets, and Telegram bot tokens are never committed to git repositories or written in plain-text configuration files. Instead, they are stored directly on Cloudflare®’s hardware-secured key vaults. Local writers chmod secret files 0600.

The Hoox CLI features deep encryption integrations to automate secret provisioning:

# 1. Inject a secure exchange credential (writes .dev.vars + puts to Cloudflare®)
hoox secrets set trade-worker BYBIT_SECRET_BINDING

# 2. Optional: dedicated testnet keys (preferred when webhook has "test": true)
hoox secrets set trade-worker BYBIT_TESTNET_KEY_BINDING
hoox secrets set trade-worker BYBIT_TESTNET_SECRET_BINDING
hoox secrets set trade-worker BINANCE_TESTNET_KEY_BINDING
hoox secrets set trade-worker BINANCE_TESTNET_SECRET_BINDING

# 3. List edge secret names for a worker (values are never printed)
hoox secrets list trade-worker

# 4. After key rotation: push mesh/system secrets only (INTERNAL_KEY_BINDING, WEBHOOK_*, …)
hoox secrets sync --system
# Alias: hoox secrets sync --required

# 5. Push all declared secrets from .dev.vars
# Partial results report synced / skipped (placeholders) / failed
hoox secrets sync

Secret sync modes

Live vs testnet exchange secrets

One unified key pair is used for all venues. The exchange (Binance / Bybit / MEXC) is chosen by the signal payload and routing config — not by secret name.

Legacy per-venue bindings (BINANCE_*, BYBIT_*, MEXC_*) still resolve as fallbacks if the unified pair is unset. If a testnet pair is missing, trade-worker falls back to the live pair and logs a warning.

See Test Trading.

Listing Edge Secrets

Running hoox secrets list queries Cloudflare® for secret names bound on the worker, without ever exposing or decrypting the actual values in your terminal. Use hoox check setup for a broader secrets-presence audit during system validation — it stays quiet when local secrets are healthy and remote names are complete, and only fails when declared secrets are missing on Cloudflare® (with hoox secrets sync hints).

---

🧱 3. Webhook Firewall & TradingView® IP Allow-listing

To ensure that only TradingView®'s official servers can fire signals to your /webhook gateway:

1. Passkey Verification: The gateway checks the apiKey property inside the JSON payload against your secure manifest in CONFIG_KV.

2. Cloudflare® WAF (Web Application Firewall): Since TradingView® publishes their official IP ranges, you can configure Cloudflare®'s edge firewall to block all webhook traffic that does not originate from these verified IPs.

# Auto-configure WAF rules to lock the /webhook route to TradingView® IPs
hoox waf configure --TradingView-only

---

📋 4. Security Best Practices Checklist

• Least Privilege API Keys: When creating API keys on Bybit, Binance, or MEXC, never enable "Withdrawal" permissions. Only check "Trade" and "Account Read" permissions.
• Credential Rotation: Automatically rotate your exchange API keys every 90 days. Deleting old keys and injecting new ones takes less than 60 seconds with hoox secrets set.
• Zero-Commit Rule: Verify that your .env.local and .dev.vars files are registered in your workspace's .gitignore file to prevent accidental pushes to public repos.
• Emergency Response: If you suspect a strategy error or exchange anomaly, immediately halt all execution via the CLI:

  hoox monitor kill-switch on
  

🔗 Next Steps

• Platform Configuration Guide — Map environment variables, secrets, and KV runtime settings.
• Local Development & Testing — Run local wrangler sandboxes with securely encrypted .dev.vars.