feat(V2): IBKR OAuth setup script + docker secrets mount + docs

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 21:40:06 +00:00
parent 55bfeca88e
commit cddf88afb4
3 changed files with 197 additions and 0 deletions
@@ -364,3 +364,66 @@ applicato al solo trading endpoint: gli endpoint dati
 ## Licenza

 Privato.
+
+## IBKR Setup
+
+IBKR uses OAuth 1.0a Self-Service for fully unattended runtime auth. Setup is
+manual one-time per account (paper + live), then the container mints live
+session tokens autonomously.
+
+### One-time setup
+
+1. Login to https://www.interactivebrokers.com → User Settings → Self-Service OAuth
+2. Generate keypairs locally:
+
+   ```bash
+   uv run python scripts/ibkr_oauth_setup.py --env testnet
+   ```
+
+   This writes RSA keys under `secrets/` and prints SHA-256 fingerprints.
+
+3. Register the two fingerprints in the IBKR portal. Receive a `consumer_key`.
+4. Get a request token + authorization URL:
+
+   ```bash
+   uv run python scripts/ibkr_oauth_setup.py --env testnet \
+       --consumer-key <K> --request-token
+   ```
+
+5. Open the URL, authorize, copy the `verifier_code`.
+6. Exchange verifier for long-lived access token (~5 years validity):
+
+   ```bash
+   uv run python scripts/ibkr_oauth_setup.py --env testnet --verifier <V>
+   ```
+
+7. Copy the printed values into `.env`:
+   - `IBKR_CONSUMER_KEY_TESTNET`
+   - `IBKR_ACCESS_TOKEN_TESTNET`
+   - `IBKR_ACCESS_TOKEN_SECRET_TESTNET`
+   - `IBKR_SIGNATURE_KEY_PATH_TESTNET`
+   - `IBKR_ENCRYPTION_KEY_PATH_TESTNET`
+   - `IBKR_ACCOUNT_ID_TESTNET` (e.g., `DU1234567` for paper)
+   - `IBKR_DH_PRIME` (hex from portal; shared paper/live)
+8. Repeat with `--env mainnet` for live trading.
+
+### Smoke test
+
+```bash
+curl https://cerbero-mcp.<dom>/mcp-ibkr/tools/get_account \
+  -H "Authorization: Bearer <TESTNET_TOKEN>" -X POST -d '{}'
+```
+
+### Key rotation
+
+```bash
+# 1. Generate new keypairs alongside existing
+uv run python scripts/ibkr_oauth_setup.py --env testnet --rotate
+
+# 2. Register new fingerprints in IBKR portal, get new consumer_key + tokens
+
+# 3. Confirm rotation (atomic swap with auto-rollback on validation fail)
+curl -X POST "https://cerbero-mcp.<dom>/admin/ibkr/rotate-keys/confirm?env=testnet" \
+  -H "Authorization: Bearer <ADMIN_TOKEN>" -H "Content-Type: application/json" \
+  -d '{"new_consumer_key":"...","new_access_token":"...","new_access_token_secret":"..."}'
+```