feat(ui): add configurable host binding

Signed-off-by: Blamp26 <98893587+Blamp26@users.noreply.github.com>

Author: Blamp26

README.md

@@ -114,11 +114,19 @@ The UI ships as a separate `ui` build (it embeds the frontend). The default inst
 Then run it:
 
 ```bash
-codebase-memory-mcp --ui=true --port=9749
+codebase-memory-mcp --ui=true --host=127.0.0.1 --port=9749
 ```
 
 Open `http://localhost:9749` in your browser. The UI runs as a background thread alongside the MCP server — it's available whenever your agent is connected.
 
+The default host is `127.0.0.1` and is persisted with the UI port. To share the UI on a trusted LAN, bind a specific local address:
+
+```bash
+codebase-memory-mcp --ui=true --host=192.168.88.26 --port=9749
+```
+
+Use `--host=0.0.0.0` only when you need all interfaces. The UI has no authentication; a non-loopback bind is reachable over the network and may expose codebase graph data and UI actions. Protect it with a firewall or trusted network, and prefer a specific LAN IP over `0.0.0.0`.
+
 ### Auto-Index
 
 Enable automatic indexing on MCP session start:

docs/CONFIGURATION.md

@@ -9,7 +9,7 @@ This page documents the configuration files that `codebase-memory-mcp` reads or
 | Global custom extension mapping | `$XDG_CONFIG_HOME/codebase-memory-mcp/config.json` | JSON | Falls back to `~/.config/codebase-memory-mcp/config.json` when `XDG_CONFIG_HOME` is unset. |
 | Per-project custom extension mapping | `{repo_root}/.codebase-memory.json` | JSON | Overrides conflicting global `extra_extensions` entries. |
 | CLI-managed runtime settings | `${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}/_config.db` | SQLite | Written by `codebase-memory-mcp config set/reset`. |
-| UI settings | `${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}/config.json` | JSON | Stores `ui_enabled` and `ui_port`. |
+| UI settings | `${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}/config.json` | JSON | Stores `ui_enabled`, `ui_port`, and numeric IPv4 `ui_host`. |
 
 ## 1. Custom File Extension Mapping
 
@@ -95,13 +95,35 @@ Current format:
 ```json
 {
   "ui_enabled": false,
-  "ui_port": 9749
+  "ui_port": 9749,
+  "ui_host": "127.0.0.1"
 }
 ```
 
 Notes:
 
 - If the UI-enabled binary has embedded assets and no UI config file exists yet, the UI auto-enables on first run.
+- `ui_host` defaults to `127.0.0.1`; config files written before this field existed remain localhost-only.
+- `--host=<IPv4>` accepts numeric IPv4 addresses only and persists the setting, just like `--port`.
+- Localhost-only UI:
+
+  ```bash
+  codebase-memory-mcp --ui=true --host=127.0.0.1 --port=9749
+  ```
+
+- Specific LAN interface (recommended when sharing on a trusted network):
+
+  ```bash
+  codebase-memory-mcp --ui=true --host=192.168.88.26 --port=9749
+  ```
+
+- All interfaces:
+
+  ```bash
+  codebase-memory-mcp --ui=true --host=0.0.0.0 --port=9749
+  ```
+
+  Binding to a non-loopback address prints a warning because the UI has no authentication, is reachable over the network, and may expose codebase graph data and UI actions. Protect it with a firewall or trusted network; prefer a specific LAN IP over `0.0.0.0`.
 - `CBM_CACHE_DIR` changes both the UI config location and the runtime settings database location.
 
 ## 4. Environment Variables

scripts/security-ui.sh

@@ -5,7 +5,7 @@ set -euo pipefail
 #
 # Audits:
 #   A. Frontend asset scan (embedded JS/CSS/HTML or graph-ui/dist/)
-#   B. HTTP server binding (must be 127.0.0.1 only)
+#   B. HTTP server binding (localhost by default; non-loopback is explicit)
 #   C. RPC proxy scope (no system()/popen() in HTTP handler path)
 #   D. CORS check (no wildcard Access-Control-Allow-Origin)
 #
@@ -139,6 +139,9 @@ echo "--- B. HTTP server binding check ---"
 # audit would go blind, so that is a hard failure, not a skip.
 HTTPD="$ROOT/src/ui/httpd.c"
 HTTP_SERVER="$ROOT/src/ui/http_server.c"
+UI_CONFIG="$ROOT/src/ui/config.h"
+UI_CONFIG_C="$ROOT/src/ui/config.c"
+MAIN="$ROOT/src/main.c"
 for f in "$HTTPD" "$HTTP_SERVER"; do
     if [[ ! -f "$f" ]]; then
         echo "BLOCKED: expected UI server source missing: $f"
@@ -147,20 +150,37 @@ for f in "$HTTPD" "$HTTP_SERVER"; do
 done
 
 if [[ -f "$HTTPD" ]]; then
-    # Must bind to 127.0.0.1 only
-    if grep -q '127\.0\.0\.1' "$HTTPD"; then
-        echo "OK: Server binds to 127.0.0.1"
+    # The safe default must remain localhost, including when loading an old
+    # config file that has no host field.
+    if [[ -f "$UI_CONFIG" ]] && grep -qE '#define CBM_UI_DEFAULT_HOST "127\.0\.0\.1"' "$UI_CONFIG" && \
+       [[ -f "$UI_CONFIG_C" ]] && grep -q 'CBM_UI_DEFAULT_HOST' "$UI_CONFIG_C"; then
+        echo "OK: Default UI host is 127.0.0.1"
     else
-        echo "BLOCKED: No 127.0.0.1 binding found in httpd.c"
+        echo "BLOCKED: Default UI host is not provably 127.0.0.1"
         FAIL=1
     fi
 
-    # Must NOT bind to 0.0.0.0 or INADDR_ANY
-    if cat "$HTTPD" "$HTTP_SERVER" 2>/dev/null | grep -E '0\.0\.0\.0|INADDR_ANY|in6addr_any' | grep -v '^\s*//' | grep -v '^\s*\*' > /dev/null 2>&1; then
-        echo "BLOCKED: Server may bind to all interfaces (0.0.0.0/INADDR_ANY found)"
+    # Non-loopback binding must travel through the explicit numeric IPv4 flag
+    # and the validated host parameter; this prevents implicit exposure.
+    if grep -q '"--host="' "$MAIN" && grep -q 'cbm_ui_host_is_valid' "$MAIN" && \
+       grep -q 'cbm_httpd_listen(const char \*host, int port)' "$HTTPD" && \
+       grep -q 'inet_pton(AF_INET' "$HTTPD"; then
+        echo "OK: Non-loopback binding requires explicit validated IPv4 configuration"
+    else
+        echo "BLOCKED: Host configuration does not prove explicit validated IPv4 binding"
         FAIL=1
+    fi
+
+    # A non-loopback bind must be visibly warned about at the point of use.
+    if grep -q 'cbm_ui_host_is_loopback' "$HTTP_SERVER" && \
+       grep -qi 'no authentication' "$HTTP_SERVER" && \
+       grep -qi 'reachable over the network' "$HTTP_SERVER" && \
+       grep -qi 'codebase graph data' "$HTTP_SERVER" && \
+       grep -qi 'firewall' "$HTTP_SERVER"; then
+        echo "OK: Non-loopback binding emits a prominent security warning"
     else
-        echo "OK: No 0.0.0.0/INADDR_ANY binding"
+        echo "BLOCKED: Non-loopback security warning is missing or incomplete"
+        FAIL=1
     fi
 fi
 

src/main.c

@@ -8,6 +8,7 @@
  *   --help          Print usage and exit
  *   --ui=true/false Enable/disable HTTP UI server (persisted)
  *   --port=N        Set HTTP UI port (persisted, default 9749)
+ *   --host=IPv4     Set HTTP UI host (persisted, default 127.0.0.1)
  *
  * Signal handling: SIGTERM/SIGINT trigger graceful shutdown.
  * Watcher runs in a background thread, polling for git changes.
@@ -28,6 +29,7 @@ enum {
     MAIN_CLI_ARGC = 2,
     MAIN_FLAG_OFF = 5, /* strlen("--ui=") */
     MAIN_PORT_OFF = 7, /* strlen("--port=") */
+    MAIN_HOST_OFF = 7, /* strlen("--host=") */
     MAIN_MAX_PORT = 65536,
     PARENT_WATCHDOG_STACK_SIZE = 64 * CBM_SZ_1K, /* watchdog only polls — tiny stack suffices */
 };
@@ -517,6 +519,7 @@ static void print_help(void) {
     printf("  --ui=true    Enable HTTP graph visualization (persisted)\n");
     printf("  --ui=false   Disable HTTP graph visualization (persisted)\n");
     printf("  --port=N     Set UI port (default 9749, persisted)\n");
+    printf("  --host=<IPv4> Set UI host (default 127.0.0.1, persisted)\n");
     printf("\nSupported agents (auto-detected):\n");
     printf("  Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode,\n");
     printf("  Antigravity, Aider, KiloCode, Kiro\n");
@@ -570,8 +573,10 @@ static int handle_subcommand(int argc, char **argv) {
     return CBM_NOT_FOUND;
 }
 
-/* Parse --ui= and --port= flags. Returns true if config was modified. */
-static bool parse_ui_flags(int argc, char **argv, cbm_ui_config_t *cfg, bool *explicit_enable) {
+/* Parse --ui=, --port=, and --host= flags. Returns -1 on invalid input,
+ * 0 when unchanged, and 1 when config was modified. */
+static int parse_ui_flags(int argc, char **argv, cbm_ui_config_t *cfg, bool *explicit_enable,
+                          char *error, size_t error_size) {
     bool changed = false;
     for (int i = SKIP_ONE; i < argc; i++) {
         if (strncmp(argv[i], "--ui=", SLEN("--ui=")) == 0) {
@@ -588,8 +593,22 @@ static bool parse_ui_flags(int argc, char **argv, cbm_ui_config_t *cfg, bool *ex
                 changed = true;
             }
         }
+        if (strcmp(argv[i], "--host") == 0) {
+            snprintf(error, error_size, "--host requires a numeric IPv4 value (use --host=<IPv4>)");
+            return -1;
+        }
+        if (strncmp(argv[i], "--host=", SLEN("--host=")) == 0) {
+            const char *host = argv[i] + MAIN_HOST_OFF;
+            if (!cbm_ui_host_is_valid(host)) {
+                snprintf(error, error_size,
+                         "invalid --host value '%s'; expected a numeric IPv4 address", host);
+                return -1;
+            }
+            snprintf(cfg->ui_host, sizeof(cfg->ui_host), "%s", host);
+            changed = true;
+        }
     }
-    return changed;
+    return changed ? 1 : 0;
 }
 
 /* Install platform-specific signal handlers. */
@@ -722,7 +741,14 @@ int main(int argc, char **argv) {
     cbm_ui_config_t ui_cfg;
     cbm_ui_config_load(&ui_cfg);
     bool explicit_ui_enable = false;
-    if (parse_ui_flags(argc, argv, &ui_cfg, &explicit_ui_enable)) {
+    char ui_flag_error[256];
+    int ui_flags_rc = parse_ui_flags(argc, argv, &ui_cfg, &explicit_ui_enable, ui_flag_error,
+                                     sizeof(ui_flag_error));
+    if (ui_flags_rc < 0) {
+        (void)fprintf(stderr, "codebase-memory-mcp: %s\n", ui_flag_error);
+        return 2;
+    }
+    if (ui_flags_rc > 0) {
         cbm_ui_config_save(&ui_cfg);
     }
     /* If the user explicitly asked for the UI but this binary has no embedded
@@ -787,7 +813,7 @@ int main(int argc, char **argv) {
     bool http_started = false;
 
     if (ui_cfg.ui_enabled && CBM_EMBEDDED_FILE_COUNT > 0) {
-        g_http_server = cbm_http_server_new(ui_cfg.ui_port);
+        g_http_server = cbm_http_server_new(ui_cfg.ui_host, ui_cfg.ui_port);
         if (g_http_server) {
             cbm_http_server_set_watcher(g_http_server, g_watcher);
             if (cbm_thread_create(&http_tid, 0, http_thread, g_http_server) == 0) {

src/ui/config.c

@@ -2,8 +2,14 @@
  * config.c — Persistent UI configuration (JSON via yyjson).
  *
  * Config file: ~/.cache/codebase-memory-mcp/config.json
- * Format: {"ui_enabled": false, "ui_port": 9749}
+ * Format: {"ui_enabled": false, "ui_port": 9749, "ui_host": "127.0.0.1"}
  */
+#ifdef _WIN32
+#include <winsock2.h>
+#include <ws2tcpip.h>
+#include <stdatomic.h>
+#endif
+
 #include "foundation/constants.h"
 #include "ui/config.h"
 #include "ui/embedded_assets.h"
@@ -15,9 +21,43 @@
 #include <yyjson/yyjson.h>
 
 #include <stdio.h>
+#include <stdint.h>
 #include <stdlib.h>
 #include <string.h>
 
+#ifndef _WIN32
+#include <arpa/inet.h>
+#endif
+
+#ifdef _WIN32
+static void cbm_ui_host_socket_init(void) {
+    static atomic_int started = 0;
+    int expected = 0;
+    if (atomic_compare_exchange_strong(&started, &expected, 1)) {
+        WSADATA wsa;
+        (void)WSAStartup(MAKEWORD(2, 2), &wsa);
+    }
+}
+#endif
+
+bool cbm_ui_host_is_valid(const char *host) {
+    struct in_addr addr;
+#ifdef _WIN32
+    cbm_ui_host_socket_init();
+#endif
+    return host && host[0] != '\0' && inet_pton(AF_INET, host, &addr) == 1;
+}
+
+bool cbm_ui_host_is_loopback(const char *host) {
+    struct in_addr addr;
+#ifdef _WIN32
+    cbm_ui_host_socket_init();
+#endif
+    if (!host || inet_pton(AF_INET, host, &addr) != 1)
+        return false;
+    return (ntohl(addr.s_addr) & UINT32_C(0xff000000)) == UINT32_C(0x7f000000);
+}
+
 /* ── Path ────────────────────────────────────────────────────── */
 
 void cbm_ui_config_path(char *buf, int bufsz) {
@@ -33,6 +73,7 @@ void cbm_ui_config_path(char *buf, int bufsz) {
 void cbm_ui_config_load(cbm_ui_config_t *cfg) {
     cfg->ui_enabled = CBM_UI_DEFAULT_ENABLED;
     cfg->ui_port = CBM_UI_DEFAULT_PORT;
+    snprintf(cfg->ui_host, sizeof(cfg->ui_host), "%s", CBM_UI_DEFAULT_HOST);
 
     char path[CBM_SZ_1K];
     cbm_ui_config_path(path, (int)sizeof(path));
@@ -88,6 +129,14 @@ void cbm_ui_config_load(cbm_ui_config_t *cfg) {
         cfg->ui_port = (int)yyjson_get_int(v_port);
     }
 
+    yyjson_val *v_host = yyjson_obj_get(root, "ui_host");
+    if (yyjson_is_str(v_host)) {
+        const char *host = yyjson_get_str(v_host);
+        if (cbm_ui_host_is_valid(host)) {
+            snprintf(cfg->ui_host, sizeof(cfg->ui_host), "%s", host);
+        }
+    }
+
     yyjson_doc_free(doc);
 }
 
@@ -112,6 +161,8 @@ void cbm_ui_config_save(const cbm_ui_config_t *cfg) {
 
     yyjson_mut_obj_add_bool(doc, root, "ui_enabled", cfg->ui_enabled);
     yyjson_mut_obj_add_int(doc, root, "ui_port", cfg->ui_port);
+    yyjson_mut_obj_add_str(doc, root, "ui_host",
+                           cbm_ui_host_is_valid(cfg->ui_host) ? cfg->ui_host : CBM_UI_DEFAULT_HOST);
 
     size_t json_len = 0;
     char *json = yyjson_mut_write(doc, YYJSON_WRITE_PRETTY, &json_len);

src/ui/config.h

@@ -1,7 +1,7 @@
 /*
  * config.h — Persistent UI configuration.
  *
- * Stores ui_enabled and ui_port in ~/.cache/codebase-memory-mcp/config.json.
+ * Stores ui_enabled, ui_port, and ui_host in ~/.cache/codebase-memory-mcp/config.json.
  * Thread-safe: load/save are independent operations on the filesystem.
  */
 #ifndef CBM_UI_CONFIG_H
@@ -12,12 +12,19 @@
 /* Default values */
 #define CBM_UI_DEFAULT_PORT 9749
 #define CBM_UI_DEFAULT_ENABLED false
+#define CBM_UI_DEFAULT_HOST "127.0.0.1"
+#define CBM_UI_HOST_MAX 16 /* INET_ADDRSTRLEN: max IPv4 text length + NUL */
 
 typedef struct {
     bool ui_enabled;
     int ui_port;
+    char ui_host[CBM_UI_HOST_MAX];
 } cbm_ui_config_t;
 
+/* Validate numeric IPv4 text and identify IPv4 loopback addresses. */
+bool cbm_ui_host_is_valid(const char *host);
+bool cbm_ui_host_is_loopback(const char *host);
+
 /* Load config from disk. Missing/corrupt file → defaults. */
 void cbm_ui_config_load(cbm_ui_config_t *cfg);