feat / Secure the Gateway with auto-generated shared mTLS certs (SEC-048)

[cardosofede]

Summary

Closes SEC-048. The Gateway was deployed unsecured (DEV=true → plain HTTP, no client-cert auth) and published on all interfaces, exposing full wallet/trade control to anyone reaching port 15888. This makes it run secured by default with TLS + mutual-cert (mTLS) auth, using one shared cert set auto-generated on first start — no manual step for the operator.

What changed

• utils/gateway_certs.py (new): single source of truth for the shared mTLS cert set. Idempotent generation (existing CA reused), mirrors client certs to root_path()/certs for the in-process GatewayHttpClient, builds the client SSLContext. All private keys encrypted with one secret (CONFIG_PASSWORD). Lives under bots/ so it's inside the shared host↔container mount, with the write path (container-local) split from the bind-mount source (host).
• gateway_service / models/gateway: dev_mode defaults False; certs generated + mounted read-only at /home/gateway/certs; GATEWAY_PASSPHRASE sourced from CONFIG_PASSWORD; bridge-mode host publish bound to 127.0.0.1 instead of 0.0.0.0.
• gateway_client / accounts_service: client speaks https + presents its cert, with the SSLContext built lazily (certs don't exist until the Gateway is started — picked up with no API restart).
• main.py: sync client certs to root_path()/certs when SSL is on.
• docker_service: deployed instances mount the shared certs at /home/hummingbot/certs and get gateway_use_ssl: true.
• docker-compose.yml: API reaches the Gateway in-network at https://gateway:15888 (host.docker.internal is unreachable once the publish is loopback-bound).

dev_mode=True remains an explicit, loopback-only escape hatch for local debugging.

Verified live (containerized deployment, gateway image v2.14.0)

• Gateway boots secured ("Running in secured mode"), certs auto-generated under bots/gateway-files/certs/, host publish bound to 127.0.0.1:15888.
• mTLS enforced (curl): no client cert → refused; client cert + passphrase → {"status":"ok"}; plain HTTP → rejected.
• API reaches the Gateway over mTLS end-to-end: GET /gateway/connectors, /gateway/chains, and a Meteora clmm/pool-info query all returned live data.
• Deployed instance received the shared certs (matching CA sha256) + gateway_use_ssl: true.
• Only unexercised criterion: a live liquidity-changing DEX transaction (needs a funded wallet).

Migration note

GATEWAY_PASSPHRASE now comes from CONFIG_PASSWORD. A Gateway whose config was previously encrypted with a different user-supplied passphrase must re-init its Gateway config. Operators on https must also set GATEWAY_URL=https://....

🤖 Generated with Claude Code

[rapcmia]

Commit 3537119

• Setup this PR with docker make setup; make deploy
• Test with gateway latest docker image v2.15.1

Started from a clean Docker deployment and call POST /gateway/start with an empty body. Confirmed bots/gateway-files/certs/ is created and Gateway starts secured ✅

• Follow-up checks confirmed bots/gateway-files/certs/ was created with the expected cert files, and Gateway logs showed startup at https://localhost:15888 in secured mode.
• POST /gateway/start with an empty JSON body returned success and started a new hummingbot/gateway:latest container on port 15888.
  • If we follow the payload for gateway/start using incorrect passphrase, it bypass the validation part and makes impression for users that it still works ❗

    #### start gateway with incorrect passphrase field in payload
    curl -s -u XXX:XXX -X POST http://localhost:8000/gateway/start -H "Content-Type: application/json" -d '
    {
      "image": "hummingbot/gateway:latest",
      "port": 15888,
      "passphrase": "XXX"
    }
    ' | jq
    {
      "success": true,
      "message": "Gateway started successfully",
      "container_id": "3655cc46fa8be1b1f3e2f4e54e9a9c4dcb86024abc34f26ac0184cd59e0cbf28",
      "port": 15888
    }
    logs: route accepted payload and started Gateway successfully; provided passphrase field did not cause route-level rejection or startup failure
    

---

Gateway blocks unsecured direct access on port 15888 ✅

• Plain http://localhost:15888/ failed with curl: (52) Empty reply from server, so the secured Gateway did not serve a usable HTTP response on the TLS port.
• https://localhost:15888/ without a client cert failed with tlsv13 alert certificate required, which confirms mTLS is enforced for direct HTTPS access.

---

For the next following tests:

• I found a bug that occur on my setup and tested on main branch as we,, see Gateway - Gateway routes stay unavailable after /gateway/start in Docker workspace #186 ❌
• I have my agent to apply a temp fix so I can continue testing this PR, attached is fix logs 06292026_gateway_network_fix.log ✅
  • HAPI successfully proxied GET /gateway/connectors, GET /gateway/chains, and the live CLMM GET /gateway/clmm/pool-info route to Gateway.
  • All three routes returned real Gateway data instead of the earlier {"detail":"Gateway service is not available"} failure.

API restart keeps Gateway routes working ✅

• Restarting only hummingbot-api after Gateway certs already existed did not break the HAPI to Gateway connection.
• After the API came back, the Gateway-backed routes still returned real connector, chain, and live pool-info data without restarting Gateway.

API starts before Gateway and recovers after Gateway starts ✅

• With HAPI already running, Gateway-backed routes failed cleanly with {"detail":"Gateway service is not available"} while Gateway was stopped.
• Starting Gateway afterward through HAPI restored the same routes immediately, without restarting the API.

Deploy a new bot instance and confirm conf_client.yml has gateway_use_ssl: true and the container mounts /home/hummingbot/certs read-only.

• Successfully deployed bots contains gateway_use_ssl:true
  

On Linux, verify unauthenticated remote access to port 15888 is still blocked by mTLS.

• Direct no-cert requests to https://localhost:15888/ and https://localhost:15888/docs failed during TLS with certificate required, which confirms mTLS is still enforced.
• Direct no-cert requests to the host IP on port 15888 returned connection refused, so remote host-IP access was not exposed during this test.

    curl -skv https://localhost:15888/
    * TLS handshake reached the server
    * Server requested a client certificate
    * OpenSSL SSL_read: ... tlsv13 alert certificate required
  
    curl -skv https://localhost:15888/docs
    * TLS handshake reached the server
    * Server requested a client certificate
    * OpenSSL SSL_read: ... tlsv13 alert certificate required
  
    curl -skv https://192.168.1.11:15888/
    * connect to 192.168.1.11 port 15888 failed: Connection refused
  
    curl -skv https://100.124.88.27:15888/
    * connect to 100.124.88.27 port 15888 failed: Connection refused
  

  • I used my agent to help investigate this, and it recommended using curl -skv, which confirmed Gateway rejected the request because no client certificate was provided ❗

[rapcmia]

• Tested using docker using make setup; make deploy
• Tested POST /gateway/start with an empty JSON body and confirmed it started Gateway container successfully on port 15888.
• Tested HAPI proxy routes GET /gateway/connectors, GET /gateway/chains, and the live Meteora GET /gateway/clmm/pool-info route, and confirmed they returned real Gateway data after Gateway was up.
• Tested the HAPI recovery flow and confirmed Gateway-backed routes returned the expected unavailable response while Gateway was down, then recovered without restarting HAPI once Gateway finished booting.
• Tested direct no-cert access to https://localhost:15888/ and https://localhost:15888/docs, and both requests were rejected during TLS with certificate required, so unsecured direct HTTPS access remained blocked.
• Confirmed integration testing also passed with hummingbot/condor#135, where the secured Gateway flow and cross-service integration completed successfully.

Note:

• Created separate issue #187