feat: explicitly configure public IP for TLS socket bindings

Author: Tinitto

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project follows versions of format `{year}.{month}.{patch_number}`.
 
 ## [Unreleased]
 
+### Added
+
+- `qpi-ui`: Added `--ip-addr` (or `QPI_IP_ADDR`, or `ipAddr` in config) to explicitly specify the public IP for binding TLS sockets. The provided IP is now properly encoded in the X509 certificate's SAN IP block.
+
+### Changed
+
+- `qpi-driver`: Updated NNG setup logic. The driver now establishes connections using the explicit NNG IP address returned by the server via `ConnectResponse`, decoupling it from the HTTP QPI address.
+
+### Fixed
+
+- `qpi-ui`: Removed the `fetchHostIPs()` autodiscovery logic which caused unintended behavior when deployed behind proxies.
+- `qpi-driver`: Fixed a race condition where the result sender process could attempt to read the CA certificate from disk before the main process had downloaded it.
+
 ## [0.0.32] - 2026-06-26
 
 ### Fixed

README.md

@@ -136,6 +136,7 @@ The Go server can be configured via CLI flags, environment variables, or a confi
 |---|---|---|---|
 | `--config-file` | `QPI_CONFIG_FILE` | `qpi.config.yml` | Path to JSON or YAML configuration file. |
 | `--domain` | `QPI_DOMAIN` | | The domain name this server is running on. |
+| `--ip-addr` | `QPI_IP_ADDR` | "127.0.0.1" | The public IP address to include in the generated TLS certificates. |
 | `--server-port` | `QPI_SERVER_PORT` | `8090` | The port this server should run on. |
 | `--tls-ca-cert-file` | `QPI_TLS_CA_CERT_FILE` | `.qpi.ca.pem` | Path to TLS root CA certificate file. |
 | `--tls-ca-key-file` | `QPI_TLS_CA_KEY_FILE` | `.qpi.ca.key` | Path to TLS root CA key file. |

qpi-driver/qpi_driver/driver.py

@@ -35,11 +35,13 @@ class HandshakeInfo:
         nng_command_port: Port allocated for NNG command dispatch.
         nng_result_port: Port allocated for NNG result collection.
         auth_token: Static authorization token assigned to the QPU.
+        nng_host: Hostname or IP for NNG connections.
     """
 
     nng_command_port: int
     nng_result_port: int
     auth_token: str
+    nng_host: str
 
 
 def _normalize_qpi_addr(qpi_addr: str) -> str:
@@ -106,6 +108,7 @@ def do_handshake(
         nng_command_port=int(data["nng_command_port"]),
         nng_result_port=int(data["nng_result_port"]),
         auth_token=data.get("auth_token", ""),
+        nng_host=data.get("nng_host") or _extract_host(qpi_addr),
     )
 
 
@@ -195,8 +198,6 @@ def send_results(
     result_queue: multiprocessing.Queue,
     res_port: int,
     nng_host: str,
-    qpi_addr: str,
-    ca_fingerprint: str,
     ca_file_path: Path,
 ) -> None:
     """Result sender process: reads Qiskit-format result dicts from result_queue
@@ -206,8 +207,6 @@ def send_results(
         result_queue: Queue used to receive result dicts from the worker.
         res_port: Port allocated for the NNG PUSH socket to return results.
         nng_host: Hostname or IP of the Go PocketBase server (for NNG TCP connections).
-        qpi_addr: The address of the QPI server to download the Certificate authority from
-        ca_fingerprint: The fingerprint of the CA file for verification of the download
         ca_file_path: Path to the CA certificate file for TLS connections.
     """
     logging.basicConfig(
@@ -221,8 +220,10 @@ def send_results(
     addr = f"tls+tcp://{nng_host}:{res_port}"
     rs_log.info("Connecting NNG PUSH → %s", addr)
 
-    tls_config = _get_tls_config(
-        qpi_addr, ca_fingerprint=ca_fingerprint, ca_file_path=ca_file_path
+    tls_config = TLSConfig(
+        TLSConfig.MODE_CLIENT,
+        server_name=nng_host,
+        ca_files=ca_file_path.as_posix(),
     )
 
     with pynng.Push0(tls_config=tls_config) as sock:
@@ -313,7 +314,7 @@ def run_driver(
         executor_type=executor_type_str,
         device_config=device_config,
     )
-    nng_host = _extract_host(qpi_addr)
+    nng_host = info.nng_host
     cmd_port = info.nng_command_port
     res_port = info.nng_result_port
 
@@ -340,28 +341,27 @@ def run_driver(
     )
     worker.start()
 
+    # 4. Ensure TLS CA cert is downloaded before starting the result sender process
+    tls_config = _get_tls_config(
+        qpi_addr, ca_fingerprint=ca_fingerprint, ca_file_path=ca_file_path
+    )
+
     # Start Result Sender Process
     result_sender = multiprocessing.Process(
         target=send_results,
         kwargs={
             "result_queue": result_queue,
             "res_port": res_port,
             "nng_host": nng_host,
-            "qpi_addr": qpi_addr,
-            "ca_fingerprint": ca_fingerprint,
             "ca_file_path": ca_file_path,
         },
         name="QPI-ResultSender",
         daemon=True,
     )
     result_sender.start()
 
-    # 4. Start NNG PULL (commands) in Main Process
     addr = f"tls+tcp://{nng_host}:{cmd_port}"
     log.info("Connecting NNG PULL → %s", addr)
-    tls_config = _get_tls_config(
-        qpi_addr, ca_fingerprint=ca_fingerprint, ca_file_path=ca_file_path
-    )
 
     try:
         with pynng.Pull0(tls_config=tls_config) as sock:

qpi-ui/internal/api/api.go

@@ -591,6 +591,7 @@ func handleQPUConnect(re *core.RequestEvent) error {
 		NNGResultPort:  qpu.NNGResultPort,
 		TLSHash:        cfg.GetTlsCaHash(),
 		AuthToken:      token,
+		NNGHost:        cfg.IpAddr,
 	}
 	return re.JSON(http.StatusOK, resp)
 }

qpi-ui/internal/api/schema.go

@@ -43,6 +43,7 @@ type ConnectResponse struct {
 	NNGResultPort  int    `json:"nng_result_port"`
 	TLSHash        string `json:"tls_hash"`
 	AuthToken      string `json:"auth_token"`
+	NNGHost        string `json:"nng_host"`
 }
 
 func (cr *ConnectResponse) SetDefaults() {
@@ -54,6 +55,7 @@ func (cr *ConnectResponse) ToMap() map[string]any {
 		"nng_command_port": cr.NNGCommandPort,
 		"nng_result_port":  cr.NNGResultPort,
 		"auth_token":       cr.AuthToken,
+		"nng_host":         cr.NNGHost,
 	}
 }
 

qpi-ui/internal/config/config.go

@@ -11,6 +11,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"log"
+	"net"
 	"os"
 	"strconv"
 	"strings"
@@ -60,6 +61,7 @@ var (
 	flagTLSCaKeyFile             string
 	flagDomainName               string
 	flagServerPort               int
+	flagIpAddr                   string
 )
 
 // AppConfig stores application-wide configuration parameters for the QPI server.
@@ -85,6 +87,7 @@ type AppConfig struct {
 	TlsCaKeyFile              string
 	DomainName                string
 	ServerPort                int
+	IpAddr                    string
 	tlsConfig                 *certKeyPair
 	parsedTlsConfig           *tls.Config
 	tlsCaConfig               *certKeyPair
@@ -191,13 +194,13 @@ func (cfg *AppConfig) StartTlsRenewalWorker(ctx context.Context) {
 				}
 
 				// regenerate certificate with new CA
-				err = generateCertAndKeyFiles(cfg.DomainName, cfg.TlsCertFile, cfg.TlsKeyFile, cfg.tlsCaConfig)
+				err = generateCertAndKeyFiles(cfg.DomainName, cfg.TlsCertFile, cfg.TlsKeyFile, cfg.tlsCaConfig, cfg.IpAddr)
 				if err != nil {
 					log.Printf("[Config] Error regenerating TLS cert and key: %v\n", err)
 					continue
 				}
 
-				cfg.tlsConfig, err = getTlsCertKeyPair(cfg.TlsCertFile, cfg.TlsKeyFile, cfg.DomainName, cfg.tlsCaConfig)
+				cfg.tlsConfig, err = getTlsCertKeyPair(cfg.TlsCertFile, cfg.TlsKeyFile, cfg.DomainName, cfg.tlsCaConfig, cfg.IpAddr)
 				if err != nil {
 					log.Printf("[Config] Error getting TLS config: %v\n", err)
 					continue
@@ -224,7 +227,7 @@ func (cfg *AppConfig) StartTlsRenewalWorker(ctx context.Context) {
 			if isCertUpForRenewal(cfg.tlsConfig, certBuffer) {
 				log.Println("[Config] TLS certificate regenerating...")
 
-				err := generateCertAndKeyFiles(cfg.DomainName, cfg.TlsCertFile, cfg.TlsKeyFile, cfg.tlsCaConfig)
+				err := generateCertAndKeyFiles(cfg.DomainName, cfg.TlsCertFile, cfg.TlsKeyFile, cfg.tlsCaConfig, cfg.IpAddr)
 				if err != nil {
 					log.Printf("[Config] Error regenerating TLS cert and key: %v\n", err)
 					continue
@@ -236,7 +239,7 @@ func (cfg *AppConfig) StartTlsRenewalWorker(ctx context.Context) {
 					continue
 				}
 
-				cfg.tlsConfig, err = getTlsCertKeyPair(cfg.TlsCertFile, cfg.TlsKeyFile, cfg.DomainName, cfg.tlsCaConfig)
+				cfg.tlsConfig, err = getTlsCertKeyPair(cfg.TlsCertFile, cfg.TlsKeyFile, cfg.DomainName, cfg.tlsCaConfig, cfg.IpAddr)
 				if err != nil {
 					log.Printf("[Config] Error loading TLS config: %v\n", err)
 					continue
@@ -314,6 +317,7 @@ func BindFlags(cmd *cobra.Command) {
 	cmd.PersistentFlags().StringVar(&flagTLSCaCertFile, "tls-ca-cert-file", DefaultTLSCaCertFile, "Path to QPI TLS certificate authority CA cert file")
 	cmd.PersistentFlags().StringVar(&flagTLSCaKeyFile, "tls-ca-key-file", DefaultTLSCaKeyFile, "Path to QPI TLS certificate authority CA key file")
 	cmd.PersistentFlags().StringVar(&flagDomainName, "domain", "", "The domain name this server is running on")
+	cmd.PersistentFlags().StringVar(&flagIpAddr, "ip-addr", "127.0.0.1", "The public IP address to include in the generated TLS certificates")
 	cmd.PersistentFlags().IntVar(&flagServerPort, "server-port", 8090, "The port this server should run on")
 	cmd.PersistentFlags().StringVar(&flagCollectionQPUs, "qpus-collection", DefaultQpusCollection, "Collection name for QPUs")
 	cmd.PersistentFlags().StringVar(&flagCollectionTimeSlots, "timeslots-collection", DefaultTimeSlotsCollection, "Collection name for Time Slots")
@@ -363,6 +367,7 @@ func NewFromFlags(cmd *cobra.Command) (*AppConfig, error) {
 	cfg.TlsKeyFile = DefaultTLSKeyFile
 	cfg.TlsCaCertFile = DefaultTLSCaCertFile
 	cfg.TlsCaKeyFile = DefaultTLSCaKeyFile
+	cfg.IpAddr = "127.0.0.1"
 
 	// Overlay Config File (if specified via env or flag)
 	configFile := flagConfigFile
@@ -393,6 +398,7 @@ func NewFromFlags(cmd *cobra.Command) (*AppConfig, error) {
 			TlsCaCertFile            *string                     `json:"tlsCaCertFile" yaml:"tlsCaCertFile"`
 			TlsCaKeyFile             *string                     `json:"tlsCaKeyFile" yaml:"tlsCaKeyFile"`
 			ServerPort               *int                        `json:"serverPort" yaml:"serverPort"`
+			IpAddr                   *string                     `json:"ipAddr" yaml:"ipAddr"`
 			CollectionTimeSlots      *string                     `json:"timeslotsCollection" yaml:"timeslotsCollection"`
 			CollectionQuantumJobs    *string                     `json:"jobsCollection" yaml:"jobsCollection"`
 			CollectionAPITokens      *string                     `json:"apiTokensCollection" yaml:"apiTokensCollection"`
@@ -434,6 +440,11 @@ func NewFromFlags(cmd *cobra.Command) (*AppConfig, error) {
 		if fileCfg.ServerPort != nil {
 			cfg.ServerPort = *fileCfg.ServerPort
 		}
+		if fileCfg.IpAddr != nil {
+			if _, err := parseIpOrErr(*fileCfg.IpAddr); err == nil {
+				cfg.IpAddr = *fileCfg.IpAddr
+			}
+		}
 		if fileCfg.CollectionQPUs != nil {
 			cfg.CollectionQPUs = *fileCfg.CollectionQPUs
 		}
@@ -554,6 +565,7 @@ func NewFromFlags(cmd *cobra.Command) (*AppConfig, error) {
 	cfg.TlsCaCertFile = resolveString("tls-ca-cert-file", "QPI_TLS_CA_CERT_FILE", cfg.TlsCaCertFile)
 	cfg.TlsCaKeyFile = resolveString("tls-ca-key-file", "QPI_TLS_CA_KEY_FILE", cfg.TlsCaKeyFile)
 	cfg.ServerPort = resolveInt("server-port", "QPI_SERVER_PORT", cfg.ServerPort)
+	cfg.IpAddr = resolveString("ip-addr", "QPI_IP_ADDR", cfg.IpAddr)
 	cfg.CollectionQPUs = resolveString("qpus-collection", "QPI_QPUS_COLLECTION", cfg.CollectionQPUs)
 	cfg.CollectionTimeSlots = resolveString("timeslots-collection", "QPI_TIMESLOTS_COLLECTION", cfg.CollectionTimeSlots)
 	cfg.CollectionQuantumJobs = resolveString("jobs-collection", "QPI_JOBS_COLLECTION", cfg.CollectionQuantumJobs)
@@ -606,7 +618,7 @@ func NewFromFlags(cmd *cobra.Command) (*AppConfig, error) {
 	}
 
 	// Load the TLS
-	cfg.tlsConfig, err = getTlsCertKeyPair(cfg.TlsCertFile, cfg.TlsKeyFile, cfg.DomainName, cfg.tlsCaConfig)
+	cfg.tlsConfig, err = getTlsCertKeyPair(cfg.TlsCertFile, cfg.TlsKeyFile, cfg.DomainName, cfg.tlsCaConfig, cfg.IpAddr)
 	if err != nil {
 		return nil, fmt.Errorf("[Config] NewFromFlags error: %w", err)
 	}
@@ -647,3 +659,13 @@ func fileExists(path string) bool {
 
 	return true
 }
+
+// parseIp parsed the IP string, returning an error if invalid
+func parseIpOrErr(value string) (net.IP, error) {
+	parsedIP := net.ParseIP(value)
+	if parsedIP == nil {
+		return nil, fmt.Errorf("invalid IP address: %s", value)
+	}
+
+	return parsedIP, nil
+}

qpi-ui/internal/config/config_test.go

@@ -22,6 +22,7 @@ jobsCollection: "yaml_quantum_jobs"
 portRangeStart: 6005
 portRangeEnd: 7005
 idleThreshold: "12s"
+ipAddr: "127.0.0.1"
 disableEmailPasswordAuth: true
 tlsCertFile: "` + tmpDir + `/test.cert.pem"
 tlsKeyFile: "` + tmpDir + `/test.key"
@@ -104,6 +105,7 @@ func TestNewFromFlags_Json(t *testing.T) {
 	jsonContent := `{
 		"jobsCollection": "json_quantum_jobs",
 		"portRangeStart": 8000,
+		"ipAddr": "127.0.0.1",
 		"tlsCertFile": "` + tmpDir + `/test.cert.pem",
 		"tlsKeyFile": "` + tmpDir + `/test.key",
 		"tlsCaCertFile": "` + tmpDir + `/test.ca.pem",
@@ -172,6 +174,7 @@ tlsCertFile: "` + certFile + `"
 tlsKeyFile: "` + keyFile + `"
 tlsCaCertFile: "` + caCertFile + `"
 tlsCaKeyFile: "` + caKeyFile + `"
+ipAddr: "127.0.0.1"
 serverPort: 8443
 `
 	if err := os.WriteFile(configFile, []byte(yamlContent), 0644); err != nil {
@@ -225,6 +228,7 @@ func TestNewFromFlags_TlsFromEnv(t *testing.T) {
 	t.Setenv("QPI_TLS_CA_CERT_FILE", caCertFile)
 	t.Setenv("QPI_TLS_CA_KEY_FILE", caKeyFile)
 	t.Setenv("QPI_SERVER_PORT", "9443")
+	t.Setenv("QPI_IP_ADDR", "127.0.0.1")
 	t.Setenv("QPI_CONFIG_FILE", emptyConfig)
 
 	cmd := &cobra.Command{}
@@ -279,6 +283,9 @@ func TestNewFromFlags_TlsFromFlags(t *testing.T) {
 	if err := cmd.PersistentFlags().Set("server-port", "10443"); err != nil {
 		t.Fatalf("failed to set server-port flag: %v", err)
 	}
+	if err := cmd.PersistentFlags().Set("ip-addr", "127.0.0.1"); err != nil {
+		t.Fatalf("failed to set ip-addr flag: %v", err)
+	}
 
 	cfg, err := NewFromFlags(cmd)
 	if err != nil {
@@ -325,6 +332,9 @@ func TestNewFromFlags_TlsAutoGenerate(t *testing.T) {
 	if err := cmd.PersistentFlags().Set("tls-ca-key-file", caKeyFile); err != nil {
 		t.Fatalf("failed to set tls-ca-key-file flag: %v", err)
 	}
+	if err := cmd.PersistentFlags().Set("ip-addr", "127.0.0.1"); err != nil {
+		t.Fatalf("failed to set ip-addr flag: %v", err)
+	}
 	if err := cmd.PersistentFlags().Set("domain", "test.local"); err != nil {
 		t.Fatalf("failed to set domain flag: %v", err)
 	}
@@ -378,7 +388,7 @@ func TestNewFromFlags_TlsReuseExisting(t *testing.T) {
 	if err != nil {
 		t.Fatalf("generateCA failed: %v", err)
 	}
-	err = generateCertAndKeyFiles("test.local", certFile, keyFile, caPair)
+	err = generateCertAndKeyFiles("test.local", certFile, keyFile, caPair, "127.0.0.1" )
 	if err != nil {
 		t.Fatalf("generateCertAndKeyFiles failed: %v", err)
 	}
@@ -402,6 +412,9 @@ func TestNewFromFlags_TlsReuseExisting(t *testing.T) {
 	if err := cmd.PersistentFlags().Set("tls-ca-key-file", caKeyFile); err != nil {
 		t.Fatalf("failed to set tls-ca-key-file flag: %v", err)
 	}
+	if err := cmd.PersistentFlags().Set("ip-addr", "127.0.0.1"); err != nil {
+		t.Fatalf("failed to set ip-addr flag: %v", err)
+	}
 
 	cfg, err := NewFromFlags(cmd)
 	if err != nil {