code-context-control 2.32.1__tar.gz → 2.33.0__tar.gz

{code_context_control-2.32.1 → code_context_control-2.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.32.1
+Version: 2.33.0
 Summary: Local code-intelligence layer for AI coding tools (Claude Code, Codex, Gemini, Copilot). Retrieve less, read less, edit safer.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0
@@ -281,6 +281,34 @@ to the C3 edit ledger so the audit trail covers platform-side changes too.
 The **Hub UI** (per-project) gains a "Bitbucket" tab with sub-views for
 Overview / Pull Requests / Branches / Activity / Admin.
 
+### Oracle Discovery API (v2.32.0)
+
+The **Oracle** is C3's optional cross-project memory agent (a local web app). As of
+v2.32.0 it can expose C3's cross-project code & memory intelligence as **tools for an
+external LLM** — point Claude (or any function-calling model) at a running Oracle and
+it can discover your projects and search code, memory, and the cross-project graph
+across all of them.
+
+Two transports share one tool core:
+
+- **MCP** (streamable HTTP/SSE) at `http://127.0.0.1:3332/mcp` — native for Claude
+  Code / Claude Desktop / any MCP client.
+- **OpenAPI REST** at `http://127.0.0.1:3331/api/discovery` — for any LLM with
+  function-calling (fetch `/openapi.json` to auto-register the tools).
+
+```bash
+# Start the Oracle (serves the REST + MCP discovery endpoints)
+python oracle/oracle_server.py --no-browser
+
+# Print the Bearer token + a ready-to-paste .mcp.json snippet
+c3 oracle api info
+```
+
+Only **read** and **safe-action** tools are exposed (no code editing); requests need a
+**Bearer token** (stored in the OS keyring) and both servers bind `127.0.0.1` by
+default. Generate, rotate, and copy the token from the dashboard's **Settings →
+Discovery API** tab. See the [Oracle Discovery API guide](oracle-guide/discovery-api.md).
+
 ---
 
 ## Tiered local AI (optional)
@@ -335,7 +363,7 @@ Real-world A/B tests: same task, with and without C3 mounted. Reports include to
 
 ## Security & privacy
 
-- **Hub binds to `127.0.0.1` by default.** Setting `host` to a non-loopback interface in `~/.c3/hub_config.json` is opt-in and warned at startup. **Do not expose the Hub to a public network without auth/TLS in front of it.**
+- **All web servers (Hub, per-project UI, Oracle) bind to `127.0.0.1` by default and are guarded against browser-based attacks even on loopback** — a Host-header allowlist (defeats DNS rebinding) plus an Origin/Referer check on every request (defeats cross-origin CSRF), with scoped, non-wildcard CORS. A malicious web page you visit therefore cannot drive C3's local endpoints. There is still **no user authentication**, so do not expose these servers to an untrusted network without auth/TLS in front. Binding to a non-loopback interface in `~/.c3/hub_config.json` (`host`) or Oracle's config (`bind_host`) is opt-in and warned at startup; add externally-facing hostnames/IPs to an `allowed_hosts` list there so the guard permits them.
 - **No telemetry by default.** The OSS package collects nothing. Opt-in Sentry crash reporting requires the `[telemetry]` extra plus both `SENTRY_DSN` and `C3_TELEMETRY_OPT_IN=1`. Even when enabled, request bodies, local variables, and prompts are stripped before sending.
 - **API keys** for third-party model providers are read from environment variables and never persisted by C3.
 - See [`SECURITY.md`](SECURITY.md) for the full hardening guide and disclosure policy.
@@ -355,6 +383,7 @@ The author may introduce a paid offering or relicense future major versions; no
 
 - **PyPI:** https://pypi.org/project/code-context-control/
 - **Changelog:** [`CHANGELOG.md`](CHANGELOG.md)
+- **Oracle Discovery API:** [`oracle-guide/discovery-api.md`](oracle-guide/discovery-api.md)
 - **Security policy:** [`SECURITY.md`](SECURITY.md)
 - **Licensing FAQ:** [`LICENSING.md`](LICENSING.md)
 - **Issues:** https://github.com/drknowhow/code-context-control/issues

{code_context_control-2.32.1 → code_context_control-2.33.0}/README.md

@@ -219,6 +219,34 @@ to the C3 edit ledger so the audit trail covers platform-side changes too.
 The **Hub UI** (per-project) gains a "Bitbucket" tab with sub-views for
 Overview / Pull Requests / Branches / Activity / Admin.
 
+### Oracle Discovery API (v2.32.0)
+
+The **Oracle** is C3's optional cross-project memory agent (a local web app). As of
+v2.32.0 it can expose C3's cross-project code & memory intelligence as **tools for an
+external LLM** — point Claude (or any function-calling model) at a running Oracle and
+it can discover your projects and search code, memory, and the cross-project graph
+across all of them.
+
+Two transports share one tool core:
+
+- **MCP** (streamable HTTP/SSE) at `http://127.0.0.1:3332/mcp` — native for Claude
+  Code / Claude Desktop / any MCP client.
+- **OpenAPI REST** at `http://127.0.0.1:3331/api/discovery` — for any LLM with
+  function-calling (fetch `/openapi.json` to auto-register the tools).
+
+```bash
+# Start the Oracle (serves the REST + MCP discovery endpoints)
+python oracle/oracle_server.py --no-browser
+
+# Print the Bearer token + a ready-to-paste .mcp.json snippet
+c3 oracle api info
+```
+
+Only **read** and **safe-action** tools are exposed (no code editing); requests need a
+**Bearer token** (stored in the OS keyring) and both servers bind `127.0.0.1` by
+default. Generate, rotate, and copy the token from the dashboard's **Settings →
+Discovery API** tab. See the [Oracle Discovery API guide](oracle-guide/discovery-api.md).
+
 ---
 
 ## Tiered local AI (optional)
@@ -273,7 +301,7 @@ Real-world A/B tests: same task, with and without C3 mounted. Reports include to
 
 ## Security & privacy
 
-- **Hub binds to `127.0.0.1` by default.** Setting `host` to a non-loopback interface in `~/.c3/hub_config.json` is opt-in and warned at startup. **Do not expose the Hub to a public network without auth/TLS in front of it.**
+- **All web servers (Hub, per-project UI, Oracle) bind to `127.0.0.1` by default and are guarded against browser-based attacks even on loopback** — a Host-header allowlist (defeats DNS rebinding) plus an Origin/Referer check on every request (defeats cross-origin CSRF), with scoped, non-wildcard CORS. A malicious web page you visit therefore cannot drive C3's local endpoints. There is still **no user authentication**, so do not expose these servers to an untrusted network without auth/TLS in front. Binding to a non-loopback interface in `~/.c3/hub_config.json` (`host`) or Oracle's config (`bind_host`) is opt-in and warned at startup; add externally-facing hostnames/IPs to an `allowed_hosts` list there so the guard permits them.
 - **No telemetry by default.** The OSS package collects nothing. Opt-in Sentry crash reporting requires the `[telemetry]` extra plus both `SENTRY_DSN` and `C3_TELEMETRY_OPT_IN=1`. Even when enabled, request bodies, local variables, and prompts are stripped before sending.
 - **API keys** for third-party model providers are read from environment variables and never persisted by C3.
 - See [`SECURITY.md`](SECURITY.md) for the full hardening guide and disclosure policy.
@@ -293,6 +321,7 @@ The author may introduce a paid offering or relicense future major versions; no
 
 - **PyPI:** https://pypi.org/project/code-context-control/
 - **Changelog:** [`CHANGELOG.md`](CHANGELOG.md)
+- **Oracle Discovery API:** [`oracle-guide/discovery-api.md`](oracle-guide/discovery-api.md)
 - **Security policy:** [`SECURITY.md`](SECURITY.md)
 - **Licensing FAQ:** [`LICENSING.md`](LICENSING.md)
 - **Issues:** https://github.com/drknowhow/code-context-control/issues

{code_context_control-2.32.1 → code_context_control-2.33.0}/cli/c3.py

@@ -85,7 +85,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.32.1"
+__version__ = "2.33.0"
 
 
 def _command_deps() -> CommandDeps:
@@ -4921,8 +4921,14 @@ def cmd_install_mcp(args):
         # Build hook commands using the Python executable that runs c3.
         # On Windows, Claude Code executes hooks via /usr/bin/bash (Git Bash), which cannot
         # parse Windows absolute paths containing parentheses (e.g. "(C3)"). Prefix with
-        # "cmd /c" so cmd.exe handles path resolution instead of bash.
-        _hook_prefix = "cmd /c " if sys.platform == "win32" else ""
+        # cmd.exe so it handles path resolution instead of bash.
+        #
+        # Use "cmd.exe" WITH the extension, not bare "cmd": Git Bash does not resolve bare
+        # "cmd" on PATH, so the old "cmd /c …" prefix silently failed to launch any hook
+        # (verified: under bash, "cmd.exe /c '<py>' '<hook>'" runs and writes the signal
+        # file; "cmd /c …" returns "cmd: command not found"). The single-quoted paths are
+        # correct — bash strips them and re-quotes for cmd.exe, preserving spaces/parens.
+        _hook_prefix = "cmd.exe /c " if sys.platform == "win32" else ""
         hook_filter_cmd    = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_filter.py'))}"
         hook_read_cmd      = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_read.py'))}"
         hook_c3read_cmd    = f"{_hook_prefix}{shlex.quote(sys.executable)} {shlex.quote(str(cli_dir / 'hook_c3read.py'))}"
@@ -4962,13 +4968,24 @@ def cmd_install_mcp(args):
             },
             {
                 "matcher": read_matcher,
-                "hooks": [{"type": "command", "command": hook_read_cmd}]
+                "hooks": [
+                    {"type": "command", "command": hook_read_cmd},
+                    {"type": "command", "command": hook_ghost_files_cmd},
+                ]
             },
             {
                 "matcher": "mcp__c3__c3_read",
                 "hooks": [
                     {"type": "command", "command": hook_c3read_cmd},
                     {"type": "command", "command": hook_c3_signal_cmd},
+                    {"type": "command", "command": hook_ghost_files_cmd},
+                ]
+            },
+            {
+                "matcher": "mcp__c3__c3_shell",
+                "hooks": [
+                    {"type": "command", "command": hook_c3_signal_cmd},
+                    {"type": "command", "command": hook_ghost_files_cmd},
                 ]
             },
             {

{code_context_control-2.32.1 → code_context_control-2.33.0}/cli/hook_ghost_files.py

@@ -212,6 +212,17 @@ def cleanup_ghost_files(ghosts: list[dict]) -> list[str]:
     return deleted
 
 
+# Tools whose output can carry shell-meta text that leaks into 0-byte files:
+# native shells, c3_shell (its `N->Mtok` filter header), and file reads whose
+# content has `-> Type` hints. A downstream shell sees `> word` and creates an
+# empty file named `word`.
+_GHOST_TRIGGER_TOOLS = (
+    "Bash", "run_shell_command",
+    "mcp__c3__c3_shell",
+    "mcp__c3__c3_read", "Read", "read_file",
+)
+
+
 def main():
     try:
         raw = sys.stdin.read()
@@ -221,8 +232,7 @@ def main():
         data = json.loads(raw)
         tool_name = data.get("tool_name", "")
 
-        # Only trigger on Bash (Claude Code) or run_shell_command (Gemini)
-        if tool_name not in ("Bash", "run_shell_command"):
+        if tool_name not in _GHOST_TRIGGER_TOOLS:
             return
 
         is_gemini = isinstance(data.get("tool_response", ""), dict)

{code_context_control-2.32.1 → code_context_control-2.33.0}/cli/hub_server.py

@@ -35,6 +35,26 @@ from services.tool_classifier import CATEGORIES
 
 app = Flask(__name__, static_folder=str(Path(__file__).parent))
 
+# Localhost-only security: Host-header allowlist + Origin/Referer CSRF guard +
+# scoped CORS. The hub manages MANY projects and exposes command-executing
+# endpoints (launch-ide, mcp-server-add, permissions), so cross-origin CSRF /
+# DNS-rebinding protection matters even though it binds loopback by default.
+# Reads bind host + optional allowed_hosts per-request from hub_config.json.
+from core.web_security import (
+    allowed_hostnames as _allowed_hostnames,
+)
+from core.web_security import (
+    install_guard as _install_web_guard,
+)
+
+
+def _hub_allowed_hosts():
+    _c = _read_hub_config()
+    return _allowed_hostnames(_c.get("host"), _c.get("allowed_hosts"))
+
+
+_install_web_guard(app, _hub_allowed_hosts)
+
 # ─── Hub config ───────────────────────────────────────────────────────────────
 
 _GLOBAL_C3_DIR = Path.home() / ".c3"
@@ -519,6 +539,11 @@ def api_projects_open():
         path = Path(path_str).resolve()
         if not path.exists():
             return jsonify({"error": f"Path does not exist: {path_str}"}), 404
+        # Only ever open directories. Opening a *file* via os.startfile would
+        # invoke its default handler (e.g. run an .exe/.bat/.lnk), so refuse
+        # anything that is not a folder.
+        if not path.is_dir():
+            return jsonify({"error": "Only directories can be opened"}), 400
 
         if sys.platform == "win32":
             os.startfile(str(path))

{code_context_control-2.32.1 → code_context_control-2.33.0}/cli/mcp_server.py

@@ -639,7 +639,9 @@ async def c3_shell(cmd: str, cwd: str = "", timeout: int = 60,
     """EXECUTE shell command — structured returns, auto-filter, ledger-aware.
     Use for tests, git, build, scripts. Returns exit_code/stdout/stderr/duration_ms.
     Auto-filters stdout >30 lines; auto-logs git mutations to the edit ledger.
-    Blocks: rm -rf / or ~, fork bombs. Soft-warns on --force, --no-verify, reset --hard.
+    Best-effort block of catastrophic commands (rm -rf of /, a top-level system dir, or
+    $HOME/~; fork bombs; whole-drive wipes) — a guard, NOT a sandbox. Soft-warns on
+    --force, --no-verify, reset --hard.
     Native Bash remains the fallback for interactive/TTY commands."""
     svc = _svc(ctx)
 

{code_context_control-2.32.1 → code_context_control-2.33.0}/cli/server.py

@@ -167,12 +167,18 @@ atexit.register(_cleanup_runtime)
 
 
 # ─── CORS middleware ──────────────────────────────────────
-@app.after_request
-def add_cors(response):
-    response.headers['Access-Control-Allow-Origin'] = '*'
-    response.headers['Access-Control-Allow-Headers'] = 'Content-Type'
-    response.headers['Access-Control-Allow-Methods'] = 'GET,POST,DELETE,OPTIONS'
-    return response
+# Localhost-only security: Host-header allowlist + Origin/Referer CSRF guard +
+# scoped CORS (no wildcard). This UI server always binds 127.0.0.1, so only
+# loopback origins are accepted. A loopback bind alone does NOT stop a web page
+# in the user's browser from driving these endpoints — see core/web_security.py.
+from core.web_security import (
+    allowed_hostnames as _allowed_hostnames,
+)
+from core.web_security import (
+    install_guard as _install_web_guard,
+)
+
+_install_web_guard(app, lambda: _allowed_hostnames(None))
 
 
 # ─── Serve the UI ─────────────────────────────────────────
@@ -283,6 +289,11 @@ def api_projects_open():
         path = Path(path_str).resolve()
         if not path.exists():
             return jsonify({"error": f"Path does not exist: {path_str}"}), 404
+        # Only ever open directories. Opening a *file* via os.startfile would
+        # invoke its default handler (e.g. run an .exe/.bat/.lnk), so refuse
+        # anything that is not a folder.
+        if not path.is_dir():
+            return jsonify({"error": "Only directories can be opened"}), 400
 
         if sys.platform == "win32":
             os.startfile(str(path))

{code_context_control-2.32.1 → code_context_control-2.33.0}/cli/tools/filter.py

@@ -64,10 +64,10 @@ def _filter_text(text: str, depth: str, svc, finalize) -> str:
     raw_tokens = res['raw_tokens']
     savings_pct = round((1 - filtered_tokens / raw_tokens) * 100, 1) if raw_tokens > 0 else 0
 
-    header = f"[filter:{method}] {raw_tokens}->{filtered_tokens}tok ({savings_pct}%saved)"
+    header = f"[filter:{method}] {raw_tokens}→{filtered_tokens}tok ({savings_pct}%saved)"
     resp = f"{header}\n{result_text}"
     return finalize("c3_filter", {"depth": depth},
-                    resp, f"{raw_tokens}->{filtered_tokens}tok",
+                    resp, f"{raw_tokens}→{filtered_tokens}tok",
                     response_tokens=filtered_tokens)
 
 

{code_context_control-2.32.1 → code_context_control-2.33.0}/cli/tools/read.py

@@ -25,13 +25,50 @@ def _coerce_list(val: Any) -> list[str] | None:
             except (json.JSONDecodeError, ValueError):
                 pass
         if val:
+            # Comma-separated symbols ("a,b,c") -> multiple targets. Function/class
+            # names never contain commas, and regex anchors (^foo$) have none either.
+            if "," in val:
+                return [s.strip() for s in val.split(",") if s.strip()]
             return [val]
     return None
 
 
+def _coerce_lines(val: Any):
+    """Coerce `lines` from MCP's string serialization into an int or list.
+
+    MCP clients sometimes serialize numbers/lists as strings (the same reason
+    `_coerce_list` exists for `symbols`). Without this, a JSON-string such as
+    "[22, 193]" or "22" falls through handle_read's range logic and the tool
+    silently returns the file *map* instead of the requested source lines.
+    """
+    if val is None or isinstance(val, (int, list, tuple)):
+        return val
+    if isinstance(val, str):
+        val = val.strip()
+        if not val:
+            return None
+        if val.startswith("["):
+            try:
+                parsed = json.loads(val)
+            except (json.JSONDecodeError, ValueError):
+                return None
+            return parsed if isinstance(parsed, list) else None
+        try:
+            return int(val)
+        except ValueError:
+            if "-" in val:  # "start-end" like "22-40"
+                a, _, b = val.partition("-")
+                try:
+                    return [int(a.strip()), int(b.strip())]
+                except ValueError:
+                    return None
+    return None
+
+
 def handle_read(file_path: str, symbols: Any = None, lines: Any = None,
                 include_docstrings: bool = True, svc=None, finalize=None) -> str:
     symbols = _coerce_list(symbols)
+    lines = _coerce_lines(lines)
     # Multi-file dispatch (parallel)
     if "," in file_path:
         paths = [p.strip() for p in file_path.split(",") if p.strip()]

{code_context_control-2.32.1 → code_context_control-2.33.0}/cli/tools/shell.py

@@ -22,9 +22,29 @@ from core import count_tokens
 _GIT_MUTATING = re.compile(
     r"^\s*git\s+(commit|add|mv|rm|merge|rebase|cherry-pick|revert|reset|restore|checkout)\b"
 )
-# Hard deny — fork bombs, rm -rf on root/home. Escape hatch: native Bash.
+# Hard deny — the handful of genuinely catastrophic, irreversible commands.
+# This is a BEST-EFFORT guard, NOT a sandbox: c3_shell runs arbitrary commands
+# by design and a determined caller can trivially reword around these patterns.
+# The escape hatch for an intentional dangerous command is native Bash.
+# Covered: rm -rf of the filesystem root / a top-level system dir / $HOME / ~,
+# the classic fork bomb, and Windows whole-drive-root wipes (del/rd/format C:\).
+# A top-level system dir only matches when it is the *whole* target, so deleting
+# a nested path like /home/me/project/build is intentionally NOT blocked.
 _BLOCKED = re.compile(
-    r"(\brm\s+-rf\s+(/|~|\$HOME)(\s|$)|:\(\)\s*\{\s*:\s*\|\s*:)"
+    r"""
+      (?<!git\ )\brm\b (?:\s+-\S+)* \s+        # rm + any flags, then a target:
+      (?:
+          /(?=\s|$|\*)                          #   filesystem root:  /   /*
+        | ~(?=/|\s|$)                            #   home dir:         ~   ~/
+        | \$HOME\b                               #   $HOME
+        | /(?:etc|usr|bin|sbin|lib|lib64|var|boot|root|home|srv|sys|proc|dev|opt)
+            (?=/?(?:\s|$|\*))                    #   a whole top-level system dir
+      )
+    | :\(\)\s*\{\s*:\s*\|\s*:\s*\}?              # fork bomb        :(){ :|: };:
+    | \b(?:format|rd|rmdir|del)\b [^\n]*?        # windows whole-drive-root wipe
+        \b[a-zA-Z]:\\?(?=\s|\*|$|["'])
+    """,
+    re.IGNORECASE | re.VERBOSE,
 )
 # Soft warn — run but prepend a caveat to the response.
 # `(?<!\w)` / `(?!\w)` anchor against word chars, so `--force` (which starts

{code_context_control-2.32.1 → code_context_control-2.33.0}/code_context_control.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.32.1
+Version: 2.33.0
 Summary: Local code-intelligence layer for AI coding tools (Claude Code, Codex, Gemini, Copilot). Retrieve less, read less, edit safer.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0
@@ -281,6 +281,34 @@ to the C3 edit ledger so the audit trail covers platform-side changes too.
 The **Hub UI** (per-project) gains a "Bitbucket" tab with sub-views for
 Overview / Pull Requests / Branches / Activity / Admin.
 
+### Oracle Discovery API (v2.32.0)
+
+The **Oracle** is C3's optional cross-project memory agent (a local web app). As of
+v2.32.0 it can expose C3's cross-project code & memory intelligence as **tools for an
+external LLM** — point Claude (or any function-calling model) at a running Oracle and
+it can discover your projects and search code, memory, and the cross-project graph
+across all of them.
+
+Two transports share one tool core:
+
+- **MCP** (streamable HTTP/SSE) at `http://127.0.0.1:3332/mcp` — native for Claude
+  Code / Claude Desktop / any MCP client.
+- **OpenAPI REST** at `http://127.0.0.1:3331/api/discovery` — for any LLM with
+  function-calling (fetch `/openapi.json` to auto-register the tools).
+
+```bash
+# Start the Oracle (serves the REST + MCP discovery endpoints)
+python oracle/oracle_server.py --no-browser
+
+# Print the Bearer token + a ready-to-paste .mcp.json snippet
+c3 oracle api info
+```
+
+Only **read** and **safe-action** tools are exposed (no code editing); requests need a
+**Bearer token** (stored in the OS keyring) and both servers bind `127.0.0.1` by
+default. Generate, rotate, and copy the token from the dashboard's **Settings →
+Discovery API** tab. See the [Oracle Discovery API guide](oracle-guide/discovery-api.md).
+
 ---
 
 ## Tiered local AI (optional)
@@ -335,7 +363,7 @@ Real-world A/B tests: same task, with and without C3 mounted. Reports include to
 
 ## Security & privacy
 
-- **Hub binds to `127.0.0.1` by default.** Setting `host` to a non-loopback interface in `~/.c3/hub_config.json` is opt-in and warned at startup. **Do not expose the Hub to a public network without auth/TLS in front of it.**
+- **All web servers (Hub, per-project UI, Oracle) bind to `127.0.0.1` by default and are guarded against browser-based attacks even on loopback** — a Host-header allowlist (defeats DNS rebinding) plus an Origin/Referer check on every request (defeats cross-origin CSRF), with scoped, non-wildcard CORS. A malicious web page you visit therefore cannot drive C3's local endpoints. There is still **no user authentication**, so do not expose these servers to an untrusted network without auth/TLS in front. Binding to a non-loopback interface in `~/.c3/hub_config.json` (`host`) or Oracle's config (`bind_host`) is opt-in and warned at startup; add externally-facing hostnames/IPs to an `allowed_hosts` list there so the guard permits them.
 - **No telemetry by default.** The OSS package collects nothing. Opt-in Sentry crash reporting requires the `[telemetry]` extra plus both `SENTRY_DSN` and `C3_TELEMETRY_OPT_IN=1`. Even when enabled, request bodies, local variables, and prompts are stripped before sending.
 - **API keys** for third-party model providers are read from environment variables and never persisted by C3.
 - See [`SECURITY.md`](SECURITY.md) for the full hardening guide and disclosure policy.
@@ -355,6 +383,7 @@ The author may introduce a paid offering or relicense future major versions; no
 
 - **PyPI:** https://pypi.org/project/code-context-control/
 - **Changelog:** [`CHANGELOG.md`](CHANGELOG.md)
+- **Oracle Discovery API:** [`oracle-guide/discovery-api.md`](oracle-guide/discovery-api.md)
 - **Security policy:** [`SECURITY.md`](SECURITY.md)
 - **Licensing FAQ:** [`LICENSING.md`](LICENSING.md)
 - **Issues:** https://github.com/drknowhow/code-context-control/issues

{code_context_control-2.32.1 → code_context_control-2.33.0}/code_context_control.egg-info/SOURCES.txt

@@ -69,6 +69,7 @@ code_context_control.egg-info/top_level.txt
 core/__init__.py
 core/config.py
 core/ide.py
+core/web_security.py
 oracle/__init__.py
 oracle/config.py
 oracle/mcp_oracle.py
@@ -168,11 +169,13 @@ tests/test_permissions.py
 tests/test_project_manager.py
 tests/test_project_manager_merge.py
 tests/test_project_tool.py
+tests/test_read_coercion.py
 tests/test_session_benchmark.py
 tests/test_session_budget.py
 tests/test_swe_bench.py
 tests/test_tool_registry.py
 tests/test_validate.py
+tests/test_web_security.py
 tests/test_windows_reliability.py
 tui/__init__.py
 tui/backend.py

code_context_control-2.33.0/core/web_security.py

@@ -0,0 +1,158 @@
+"""Localhost-only security guard for C3's Flask dashboards (UI, Hub, Oracle).
+
+Why this exists
+---------------
+C3's web servers bind to loopback (``127.0.0.1``) by default. A loopback bind
+keeps the server off the LAN, but it does **not** protect against requests made
+by a web page running in the user's own browser. Two classic attacks defeat a
+"loopback is safe" assumption:
+
+* **Cross-origin / CSRF** — any website the user visits can ``fetch()`` against
+  ``http://localhost:<port>/...``. With no auth and a permissive CORS policy,
+  that page could drive state-changing endpoints (launch an IDE command, add a
+  malicious MCP server, downgrade permissions, wipe data).
+* **DNS rebinding** — an attacker domain re-resolves to ``127.0.0.1`` after the
+  page loads, so the browser sends requests to the local server with the
+  *attacker's* hostname in the ``Host`` header.
+
+This module adds two cheap, standard defenses that together close that gap
+without requiring the dashboard JavaScript to change (same-origin requests pass
+naturally):
+
+1. **Host-header allowlist** — defeats DNS rebinding. The rebound request
+   carries the attacker's hostname in ``Host``; anything not in the allowlist is
+   rejected.
+2. **Origin/Referer check on state-changing requests** — defeats cross-origin
+   CSRF. Browsers always attach ``Origin`` to ``POST``/``PUT``/``DELETE``/
+   ``PATCH`` (cross-origin *and* same-origin), so a mismatched origin is a
+   reliable CSRF signal.
+
+Non-browser clients (curl, the Oracle Discovery REST/MCP consumers) send no
+``Origin`` and a loopback ``Host``, so they are unaffected. Bearer-token auth
+(Oracle discovery) still applies on top of this guard.
+
+For an intentional non-loopback bind (an explicit, already-warned opt-in), pass
+the configured bind host so the user can still reach their own dashboard; remote
+hosts that need access can be added via the optional ``extra`` argument
+(wired from an ``allowed_hosts`` config list by the caller).
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from urllib.parse import urlsplit
+
+# Hostnames that always denote "this machine". Note: a literal ``0.0.0.0`` never
+# appears as a browser Host header, so it is intentionally excluded — binding to
+# 0.0.0.0 means the client connects by some concrete IP/name, which must be added
+# via ``extra`` (``allowed_hosts`` config) by the operator.
+_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "[::1]"})
+_MUTATING_METHODS = frozenset({"POST", "PUT", "DELETE", "PATCH"})
+
+
+def _hostname(value: str | None) -> str:
+    """Extract a bare, lowercased hostname from a Host header or Origin/Referer URL.
+
+    Handles values with or without a scheme and with or without a port, including
+    IPv6 literals like ``[::1]:3333``.
+    """
+    if not value:
+        return ""
+    value = value.strip()
+    # A bare Host header ("localhost:3333") has no scheme; prefix "//" so urlsplit
+    # parses it as a netloc rather than a path.
+    if "://" not in value:
+        value = "//" + value
+    try:
+        host = urlsplit(value).hostname or ""
+    except ValueError:
+        return ""
+    return host.lower()
+
+
+def allowed_hostnames(bind_host: str | None = None,
+                      extra: Iterable[str] | None = None) -> set[str]:
+    """Build the set of acceptable hostnames for this server.
+
+    Always includes loopback names. ``bind_host`` (unless it is the wildcard
+    ``0.0.0.0`` or empty) and any ``extra`` hosts are added so an intentional
+    non-loopback deployment remains reachable.
+    """
+    hosts = set(_LOOPBACK_HOSTS)
+    bh = (bind_host or "").strip().lower()
+    if bh and bh not in ("0.0.0.0", "::", "*"):
+        hosts.add(bh)
+    if extra:
+        for h in extra:
+            h = (h or "").strip().lower()
+            if h:
+                hosts.add(h)
+    return hosts
+
+
+def check_request(request, allowed: set[str]) -> tuple[bool, str]:
+    """Return ``(ok, reason)``. ``ok == False`` means the request must be 403'd.
+
+    ``request`` is a Flask request (anything exposing ``.host``, ``.method`` and
+    ``.headers.get``).
+    """
+    # 1) Host-header allowlist — anti DNS-rebinding.
+    host = _hostname(getattr(request, "host", "") or "")
+    if host and host not in allowed:
+        return False, f"host '{host}' is not allowlisted"
+
+    # 2) Origin check — anti cross-origin CSRF. Browsers always send Origin on
+    #    state-changing requests, so a mismatch is a reliable CSRF signal. When
+    #    Origin is absent (typical for curl / API clients), fall back to Referer
+    #    only for mutating methods; a fully header-less request is treated as a
+    #    non-browser caller and allowed (it cannot be a CSRF from a page).
+    origin = request.headers.get("Origin")
+    if origin:
+        if _hostname(origin) not in allowed:
+            return False, "cross-origin request blocked (Origin)"
+    elif request.method in _MUTATING_METHODS:
+        referer = request.headers.get("Referer")
+        if referer and _hostname(referer) not in allowed:
+            return False, "cross-origin request blocked (Referer)"
+    return True, ""
+
+
+def cors_origin(request, allowed: set[str]) -> str | None:
+    """Echo the request Origin in Access-Control-Allow-Origin only if it is
+    same-origin/allowlisted. The wildcard ``*`` is never used.
+    """
+    origin = request.headers.get("Origin")
+    if origin and _hostname(origin) in allowed:
+        return origin
+    return None
+
+
+def install_guard(app, get_allowed: Callable[[], set[str]]) -> None:
+    """Register the Host/Origin guard and a tightened CORS policy on a Flask app.
+
+    ``get_allowed`` is called per-request so live config changes (e.g. a hub
+    ``host`` edit or an ``allowed_hosts`` list) are honoured without a restart.
+    Registering this BEFORE any other ``before_request`` (e.g. a bearer-token
+    guard) ensures cross-origin requests are rejected first.
+    """
+    from flask import jsonify, request
+
+    @app.before_request
+    def _c3_security_guard():  # noqa: ANN202 - Flask hook
+        # Let CORS preflight through; the after_request handler answers it and
+        # only reflects an allowlisted Origin, so disallowed origins still fail.
+        if request.method == "OPTIONS":
+            return None
+        ok, reason = check_request(request, get_allowed())
+        if not ok:
+            return jsonify({"error": f"blocked: {reason}"}), 403
+        return None
+
+    @app.after_request
+    def _c3_cors(response):  # noqa: ANN202 - Flask hook
+        origin = cors_origin(request, get_allowed())
+        if origin:
+            response.headers["Access-Control-Allow-Origin"] = origin
+            response.headers["Vary"] = "Origin"
+            response.headers["Access-Control-Allow-Headers"] = "Content-Type, Authorization"
+            response.headers["Access-Control-Allow-Methods"] = "GET,POST,PUT,DELETE,OPTIONS"
+        return response

{code_context_control-2.32.1 → code_context_control-2.33.0}/oracle/mcp_oracle.py

@@ -23,12 +23,19 @@ from oracle.services import api_auth
 logger = logging.getLogger("oracle.mcp")
 
 _INSTRUCTIONS = (
-    "C3 Oracle Discovery — cross-project code & memory intelligence as tools. "
-    "Start with list_projects to see available projects, then use c3_search_cross "
-    "or search_facts to discover across all of them, or the per-project tools "
-    "(c3_search, c3_read, c3_compress, query_memory, read_graph) with a project_path. "
-    "suggest_action creates a PENDING suggestion for human approval; delegate_task runs "
-    "a configured Oracle agent. No code-editing tools are exposed."
+    "C3 Oracle Discovery — use C3's cross-project code & memory intelligence as tools.\n"
+    "\n"
+    "Recommended workflow:\n"
+    "1. list_projects — see which C3 projects exist (names + absolute paths).\n"
+    "2. Discover across ALL projects: search_facts (memory) or c3_search_cross (code).\n"
+    "3. Narrow to one project using its path: c3_search to find code; c3_compress "
+    "(mode='map') to see a file's shape before reading; c3_read for exact content; "
+    "query_memory / read_graph / cross_insights for that project's memory.\n"
+    "\n"
+    "Notes: per-project tools REQUIRE a `project_path` taken from list_projects. Every tool "
+    "returns JSON. suggest_action creates a PENDING suggestion for a human to approve (not a "
+    "direct write); delegate_task runs a configured Oracle agent. Read + safe-action tiers "
+    "only — no code-editing tools are exposed."
 )