@ictechgy/context-guard 0.4.9 → 0.4.10

package/plugins/context-guard/bin/context-guard-experiments

@@ -26,6 +26,7 @@ from socketserver import TCPServer
 from pathlib import Path
 import stat
 import sys
+import time
 from typing import Any, NoReturn
 import unicodedata
 from urllib.parse import urlparse
@@ -89,6 +90,7 @@ LOCAL_PROXY_SENSITIVE_HEADER_NAMES = {
     "cookie",
     "set-cookie",
 }
+LOCAL_PROXY_NONCE_HEADER = "X-ContextGuard-Proxy-Nonce"
 LOCAL_PROXY_HOP_BY_HOP_HEADERS = {
     "connection",
     "keep-alive",
@@ -336,8 +338,8 @@ EXPERIMENTS: tuple[Experiment, ...] = (
             "context-guard experiments plan local-proxy",
             "context-guard experiments plan local-proxy-external-forwarding",
             "context-guard experiments record local-proxy-runtime-gate --ledger-jsonl <path>",
-            "context-guard experiments serve local-proxy --bind-host 127.0.0.1 --bind-port <port> --target-host 127.0.0.1 --target-port <port> --runtime-gate-ack --forwarding-gate-ack --once",
-            "context-guard experiments serve local-proxy --diagnostic-ledger-jsonl <path> ...",
+            "context-guard experiments serve local-proxy --bind-host 127.0.0.1 --bind-port <port> --target-host 127.0.0.1 --target-port <port> --runtime-gate-ack --forwarding-gate-ack --once --ready-file <path>",
+            "context-guard experiments serve local-proxy --ready-file <ready-file> --diagnostic-ledger-jsonl <path> ...",
         ),
         opt_in_flags=(
             "plan local-proxy",
@@ -356,6 +358,7 @@ EXPERIMENTS: tuple[Experiment, ...] = (
             "--max-request-bytes",
             "--max-response-bytes",
             "--diagnostic-ledger-jsonl",
+            "--ready-file",
             "--external-forwarding-intent",
             "--external-forwarding-design-ack",
             "--allow-host",
@@ -372,10 +375,11 @@ EXPERIMENTS: tuple[Experiment, ...] = (
         ),
         evidence_contract=(
             "Gate rows require localhost-only bind/target metadata and explicit runtime gate acknowledgement. Serve "
-            "evidence requires loopback-only bind/target IPs, explicit forwarding acknowledgement, no credential "
-            "forwarding or persistence, bounded bytes/timeouts, and optional diagnostic ledger rows that remain "
-            "shifted-cost evidence only. External-forwarding design plans require threat model notes, explicit "
-            "allowlists, credential redaction policy, and provider-evidence boundaries before any future runtime."
+            "evidence requires loopback-only bind/target IPs, a private ready-file nonce handoff, explicit forwarding "
+            "acknowledgement, no credential forwarding or persistence, bounded bytes/timeouts, and optional diagnostic "
+            "ledger rows that remain shifted-cost evidence only. External-forwarding design plans require threat model "
+            "notes, explicit allowlists, credential redaction policy, and provider-evidence boundaries before any future "
+            "runtime."
         ),
     ),
 )
@@ -2684,8 +2688,13 @@ def coalesce_local_proxy_bool(args: argparse.Namespace, payload: dict[str, Any],
     return parse_local_proxy_json_bool(payload.get(key))
 
 
-def local_proxy_plan_payload(args: argparse.Namespace) -> dict[str, Any]:
-    input_payload, input_meta = read_local_proxy_payload(args)
+def local_proxy_plan_payload(
+    args: argparse.Namespace,
+    input_payload: dict[str, Any] | None = None,
+    input_meta: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    if input_payload is None or input_meta is None:
+        input_payload, input_meta = read_local_proxy_payload(args)
     bind_host_raw = coalesce_local_proxy_value(args, input_payload, "bind_host", "bind_host")
     bind_port_raw = coalesce_local_proxy_value(args, input_payload, "bind_port", "bind_port")
     target_host_raw = coalesce_local_proxy_value(args, input_payload, "target_host", "target_host")
@@ -3001,8 +3010,8 @@ def command_record_local_proxy_runtime_gate(args: argparse.Namespace) -> int:
 
 
 def local_proxy_forward_payload(args: argparse.Namespace) -> dict[str, Any]:
-    payload = local_proxy_plan_payload(args)
-    input_payload, _input_meta = read_local_proxy_payload(args)
+    input_payload, input_meta = read_local_proxy_payload(args)
+    payload = local_proxy_plan_payload(args, input_payload=input_payload, input_meta=input_meta)
     forwarding_gate_ack, forwarding_gate_ack_valid = coalesce_local_proxy_bool(
         args,
         input_payload,
@@ -3085,6 +3094,15 @@ def local_proxy_forward_payload(args: argparse.Namespace) -> dict[str, Any]:
         "bytes_written": 0,
         "reason": None if diagnostic_ledger_raw else "not_requested",
     }
+    payload["client_auth"] = {
+        "required": True,
+        "type": "nonce_header",
+        "header": LOCAL_PROXY_NONCE_HEADER,
+        "delivery": "ready_file",
+        "ready_file_required": True,
+        "nonce_in_public_output": False,
+        "nonce_forwarded_upstream": False,
+    }
     payload["_diagnostic_ledger_write_path"] = diagnostic_ledger_write_path
     payload["forward_result"] = None
 
@@ -3210,6 +3228,12 @@ def local_proxy_has_sensitive_headers(headers: Any) -> list[str]:
     found: list[str] = []
     for name, value in headers.items():
         lower = str(name).lower()
+        if lower == LOCAL_PROXY_NONCE_HEADER.lower():
+            # The per-run proxy nonce is a local client-auth secret delivered only
+            # through the 0600 ready file. It is validated before this check and is
+            # never forwarded upstream; do not let random nonce bytes
+            # probabilistically trip the generic secret-like header detector.
+            continue
         if lower in LOCAL_PROXY_SENSITIVE_HEADER_NAMES:
             found.append(lower)
         elif local_proxy_secret_like(name):
@@ -3240,7 +3264,7 @@ def local_proxy_response_headers(headers: Any) -> list[tuple[str, str]]:
     return result
 
 
-def write_local_proxy_ready_file(path: str | None, *, bind_host: str, bind_port: int) -> None:
+def write_local_proxy_ready_file(path: str | None, *, bind_host: str, bind_port: int, auth_nonce: str) -> None:
     if not path:
         return
     ready_payload = {
@@ -3254,6 +3278,14 @@ def write_local_proxy_ready_file(path: str | None, *, bind_host: str, bind_port:
             "host": bind_host,
             "port": bind_port,
         },
+        "client_auth": {
+            "required": True,
+            "type": "nonce_header",
+            "header": LOCAL_PROXY_NONCE_HEADER,
+            "nonce": auth_nonce,
+            "forwarded_upstream": False,
+            "public_output": False,
+        },
     }
     data = json.dumps(ready_payload, sort_keys=True).encode("utf-8") + b"\n"
     write_regular_file_no_follow_exclusive(Path(path), data, label="local proxy ready file", mode=0o600)
@@ -3268,6 +3300,7 @@ def serve_local_proxy_once(payload: dict[str, Any], *, ready_file: str | None =
     max_request_bytes = int(limits["max_request_bytes"])
     max_response_bytes = int(limits["max_response_bytes"])
     timeout_seconds = float(limits["timeout_seconds"])
+    auth_nonce = secrets.token_urlsafe(32)
     server_result: dict[str, Any] = {
         "served_once": False,
         "forwarded": False,
@@ -3283,16 +3316,30 @@ def serve_local_proxy_once(payload: dict[str, Any], *, ready_file: str | None =
         "sensitive_headers_blocked": [],
         "listener_started": False,
         "ready_file_written": False,
+        "client_auth_required": True,
+        "client_auth_header": LOCAL_PROXY_NONCE_HEADER,
+        "client_auth_delivered": False,
+        "client_auth_nonce_forwarded": False,
+        "auth_failures": 0,
     }
 
-    def finish_blocked(handler: BaseHTTPRequestHandler, status_code: int, reason: str, *, sensitive: list[str] | None = None) -> None:
-        server_result.update({
-            "served_once": True,
+    def finish_blocked(
+        handler: BaseHTTPRequestHandler,
+        status_code: int,
+        reason: str,
+        *,
+        sensitive: list[str] | None = None,
+        consume_once: bool = True,
+    ) -> None:
+        updates = {
             "forwarded": False,
             "blocked_reason": reason,
             "downstream_status": status_code,
             "sensitive_headers_blocked": sorted(set(sensitive or [])),
-        })
+        }
+        if consume_once:
+            updates["served_once"] = True
+        server_result.update(updates)
         body = json.dumps({"status": "blocked", "reason": reason}, sort_keys=True).encode("utf-8")
         handler.send_response(status_code)
         handler.send_header("Content-Type", "application/json")
@@ -3309,9 +3356,28 @@ def serve_local_proxy_once(payload: dict[str, Any], *, ready_file: str | None =
         def log_message(self, format: str, *args: Any) -> None:  # noqa: A002 - BaseHTTPRequestHandler API.
             return
 
+        def authorize_request(self) -> bool:
+            values = self.headers.get_all(LOCAL_PROXY_NONCE_HEADER, [])
+            if len(values) == 0:
+                server_result["auth_failures"] = int(server_result.get("auth_failures", 0)) + 1
+                finish_blocked(self, 403, "missing_proxy_nonce", consume_once=False)
+                return False
+            if len(values) != 1:
+                server_result["auth_failures"] = int(server_result.get("auth_failures", 0)) + 1
+                finish_blocked(self, 403, "duplicate_proxy_nonce", consume_once=False)
+                return False
+            candidate = str(values[0])
+            if not secrets.compare_digest(candidate, auth_nonce):
+                server_result["auth_failures"] = int(server_result.get("auth_failures", 0)) + 1
+                finish_blocked(self, 403, "invalid_proxy_nonce", consume_once=False)
+                return False
+            return True
+
         def do_CONNECT(self) -> None:
             server_result["request_method"] = "CONNECT"
             server_result.update(local_proxy_request_target_meta(self.path))
+            if not self.authorize_request():
+                return
             finish_blocked(self, 405, "connect_tunneling_not_allowed")
 
         def do_HEAD(self) -> None:
@@ -3332,6 +3398,8 @@ def serve_local_proxy_once(payload: dict[str, Any], *, ready_file: str | None =
         def block_method(self) -> None:
             server_result["request_method"] = self.command
             server_result.update(local_proxy_request_target_meta(self.path))
+            if not self.authorize_request():
+                return
             finish_blocked(self, 405, "method_not_allowed")
 
         def do_DELETE(self) -> None:
@@ -3346,6 +3414,8 @@ def serve_local_proxy_once(payload: dict[str, Any], *, ready_file: str | None =
         def forward_request(self) -> None:
             server_result["request_method"] = self.command
             server_result.update(local_proxy_request_target_meta(self.path))
+            if not self.authorize_request():
+                return
             if local_proxy_secret_like(self.path):
                 finish_blocked(self, 400, "secret_like_request_target")
                 return
@@ -3435,8 +3505,9 @@ def serve_local_proxy_once(payload: dict[str, Any], *, ready_file: str | None =
     httpd.timeout = timeout_seconds
     try:
         try:
-            write_local_proxy_ready_file(ready_file, bind_host=bind_host, bind_port=bind_port)
+            write_local_proxy_ready_file(ready_file, bind_host=bind_host, bind_port=bind_port, auth_nonce=auth_nonce)
             server_result["ready_file_written"] = bool(ready_file)
+            server_result["client_auth_delivered"] = bool(ready_file)
             server_result["listener_started"] = True
         except RegistryError as exc:
             server_result.update({
@@ -3447,8 +3518,14 @@ def serve_local_proxy_once(payload: dict[str, Any], *, ready_file: str | None =
                 "error": sanitize_local_proxy_value(str(exc)),
             })
             return server_result
-        httpd.handle_request()
-        if not server_result["served_once"]:
+        deadline = time.monotonic() + timeout_seconds
+        while not server_result["served_once"]:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            httpd.timeout = max(0.001, min(timeout_seconds, remaining))
+            httpd.handle_request()
+        if not server_result["served_once"] and not server_result.get("blocked_reason"):
             server_result.update({
                 "blocked_reason": "timeout_waiting_for_request",
                 "downstream_status": None,
@@ -3461,6 +3538,10 @@ def serve_local_proxy_once(payload: dict[str, Any], *, ready_file: str | None =
 def command_serve_local_proxy(args: argparse.Namespace) -> int:
     payload = local_proxy_forward_payload(args)
     diagnostic_ledger = payload.get("diagnostic_ledger") if isinstance(payload.get("diagnostic_ledger"), dict) else {}
+    if payload["status"] == "ready_to_serve" and not args.ready_file:
+        payload["status"] = "blocked_until_local_proxy_forwarding_ready"
+        payload["review_plan"]["readiness_blockers"].append("missing_ready_file_for_proxy_nonce")
+        diagnostic_ledger["reason"] = "not_forwarded" if diagnostic_ledger.get("write_requested") else diagnostic_ledger.get("reason")
     if payload["status"] == "ready_to_serve" and diagnostic_ledger.get("write_requested"):
         try:
             preflight_append_jsonl_no_follow(

package/plugins/context-guard/bin/context-guard-failed-nudge

@@ -484,6 +484,9 @@ def count_consecutive_failures(entries: list[dict], fp: str) -> int:
 
 
 def main() -> int:
+    if any(arg in {"-h", "--help"} for arg in sys.argv[1:]):
+        print("ContextGuard helper: context-guard-failed-nudge")
+        return 0
     raw_payload, oversized = read_bounded_stdin_text()
     if oversized:
         sys.stderr.write("context-guard-failed-nudge: oversized hook JSON skipped\n")

package/plugins/context-guard/bin/context-guard-filter

@@ -16,6 +16,7 @@ from pathlib import Path
 import re
 import shlex
 import signal
+import stat
 import subprocess
 import sys
 import threading
@@ -86,16 +87,171 @@ def compact(text: str, limit: int = 160) -> str:
     return text[: max(0, limit - 20)] + f"…[trimmed:{len(text)}]"
 
 
-def read_json_limited(path: Path) -> tuple[Any | None, list[str]]:
+ALLOWED_FIRST_ABSOLUTE_SYMLINKS = {
+    "tmp": Path("/private/tmp"),
+    "var": Path("/private/var"),
+}
+NO_FOLLOW_SUPPORTED = hasattr(os, "O_NOFOLLOW")
+DIR_FD_OPEN_SUPPORTED = bool(os.supports_dir_fd and os.open in os.supports_dir_fd)
+DIR_FD_STAT_SUPPORTED = bool(os.supports_dir_fd and os.stat in os.supports_dir_fd)
+DIR_FD_MKDIR_SUPPORTED = bool(os.supports_dir_fd and os.mkdir in os.supports_dir_fd)
+NONBLOCK_SUPPORTED = hasattr(os, "O_NONBLOCK")
+
+
+def os_error_detail(exc: OSError) -> str:
+    detail = exc.strerror or str(exc) or exc.__class__.__name__
+    if exc.errno is not None:
+        return f"{detail} (errno {exc.errno})"
+    return detail
+
+
+def normalized_link_target(parent: Path, raw_target: str) -> Path:
+    target = Path(raw_target)
+    if not target.is_absolute():
+        target = parent / target
+    return Path(os.path.normpath(str(target)))
+
+
+def normalize_allowed_first_absolute_symlink(path: Path) -> Path:
+    if not path.is_absolute() or len(path.parts) < 2:
+        return path
+    first = path.parts[1]
+    expected = ALLOWED_FIRST_ABSOLUTE_SYMLINKS.get(first)
+    if expected is None:
+        return path
+    link = Path(path.anchor) / first
+    try:
+        if not stat.S_ISLNK(os.lstat(link).st_mode):
+            return path
+        if normalized_link_target(Path(path.anchor), os.readlink(link)) != expected:
+            return path
+    except OSError:
+        return path
+    return expected.joinpath(*path.parts[2:])
+
+
+def normalize_config_path(path: Path) -> Path:
+    path = path.expanduser()
+    if any(part == ".." for part in path.parts):
+        raise OSError("config path must not contain parent traversal")
+    if not path.is_absolute():
+        path = Path.cwd() / path
+    return normalize_allowed_first_absolute_symlink(Path(os.path.normpath(str(path))))
+
+
+def no_follow_dir_flags() -> int:
+    if not NO_FOLLOW_SUPPORTED:
+        raise OSError("O_NOFOLLOW is required for safe config reads")
+    flags = os.O_RDONLY | os.O_NOFOLLOW
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if hasattr(os, "O_DIRECTORY"):
+        flags |= os.O_DIRECTORY
+    return flags
+
+
+def no_follow_file_flags() -> int:
+    if not NO_FOLLOW_SUPPORTED:
+        raise OSError("O_NOFOLLOW is required for safe config reads")
+    if not NONBLOCK_SUPPORTED:
+        raise OSError("O_NONBLOCK is required for safe config reads")
+    flags = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if hasattr(os, "O_NOCTTY"):
+        flags |= os.O_NOCTTY
+    return flags
+
+
+def open_config_parent_no_follow(path: Path) -> int:
+    if not DIR_FD_OPEN_SUPPORTED:
+        raise OSError("dir_fd open support is required for safe config reads")
+    flags = no_follow_dir_flags()
+    if path.is_absolute():
+        anchor = path.anchor or os.sep
+        current_fd = os.open(anchor, os.O_RDONLY | (os.O_CLOEXEC if hasattr(os, "O_CLOEXEC") else 0))
+        parts = path.parts[1:-1]
+    else:
+        current_fd = os.open(".", flags)
+        parts = path.parts[:-1]
+    try:
+        for part in parts:
+            if part in {"", "."}:
+                continue
+            if part == "..":
+                raise OSError("config path must not contain parent traversal")
+            next_fd = os.open(part, flags, dir_fd=current_fd)
+            try:
+                if not stat.S_ISDIR(os.fstat(next_fd).st_mode):
+                    raise OSError("config path must not traverse non-directory components")
+            except Exception:
+                os.close(next_fd)
+                raise
+            os.close(current_fd)
+            current_fd = next_fd
+        owned_fd = current_fd
+        current_fd = -1
+        return owned_fd
+    finally:
+        if current_fd >= 0:
+            os.close(current_fd)
+
+
+def read_config_text_no_follow(path: Path, max_bytes: int) -> tuple[str | None, list[str]]:
+    parent_fd = -1
+    fd = -1
     try:
-        size = path.stat().st_size
-        if size > MAX_CONFIG_BYTES:
-            return None, [f"config file too large: {size}>{MAX_CONFIG_BYTES} bytes"]
-        raw = path.read_text(encoding="utf-8")
+        path = normalize_config_path(path)
+        parent_fd = open_config_parent_no_follow(path)
+        leaf = path.name
+        if leaf in {"", ".", ".."}:
+            return None, ["config path must name a regular file"]
+        if not DIR_FD_STAT_SUPPORTED:
+            raise OSError("dir_fd stat support is required for safe config reads")
+        try:
+            st = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
+        except FileNotFoundError:
+            return None, ["could not read config: missing file"]
+        if not stat.S_ISREG(st.st_mode):
+            return None, ["config must be a regular file"]
+        if st.st_size > max_bytes:
+            return None, [f"config file too large: {st.st_size}>{max_bytes} bytes"]
+        fd = os.open(leaf, no_follow_file_flags(), dir_fd=parent_fd)
+        fst = os.fstat(fd)
+        if not stat.S_ISREG(fst.st_mode):
+            return None, ["config must be a regular file"]
+        if fst.st_size > max_bytes:
+            return None, [f"config file too large: {fst.st_size}>{max_bytes} bytes"]
+        chunks: list[bytes] = []
+        remaining = max_bytes + 1
+        while remaining > 0:
+            chunk = os.read(fd, min(64 * 1024, remaining))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        raw = b"".join(chunks)
+        if len(raw) > max_bytes:
+            return None, [f"config file too large: >{max_bytes} bytes"]
+        try:
+            return raw.decode("utf-8"), []
+        except UnicodeDecodeError as exc:
+            return None, [f"could not decode config UTF-8: {exc.reason}"]
     except OSError as exc:
-        return None, [f"could not read config: {exc.strerror or exc.__class__.__name__}"]
+        return None, [f"could not read config safely: {os_error_detail(exc)}"]
+    finally:
+        if fd >= 0:
+            os.close(fd)
+        if parent_fd >= 0:
+            os.close(parent_fd)
+
+
+def read_json_limited(path: Path) -> tuple[Any | None, list[str]]:
+    raw, read_errors = read_config_text_no_follow(path, MAX_CONFIG_BYTES)
+    if read_errors:
+        return None, read_errors
     try:
-        return json.loads(raw), []
+        return json.loads(raw if raw is not None else ""), []
     except json.JSONDecodeError as exc:
         return None, [f"invalid JSON at line {exc.lineno}: {exc.msg}"]
 

package/plugins/context-guard/bin/context-guard-guard-read

@@ -607,6 +607,9 @@ def deny_response(reason: str) -> dict[str, Any]:
 
 
 def main() -> int:
+    if any(arg in {"-h", "--help"} for arg in sys.argv[1:]):
+        print("ContextGuard helper: context-guard-guard-read")
+        return 0
     if truthy_disabled(env_value(GUARD_ENV, LEGACY_GUARD_ENV)):
         print("{}")
         return 0