@ictechgy/context-guard 0.4.8 → 0.4.10

package/context-guard-kit/hook_secret_patterns.py

@@ -1,43 +0,0 @@
-#!/usr/bin/env python3
-"""Shared high-confidence secret patterns for hook-visible text.
-
-These patterns are intentionally narrower than the full output sanitizer: hooks
-use them on user-controlled path labels and short diagnostics where false
-positives should redact the whole label rather than rewrite large command
-output. Keep alternatives bounded or structurally linear; hooks run before any
-downstream sanitizer can protect their own stderr/JSON output.
-"""
-from __future__ import annotations
-
-import re
-
-
-CONTROL_CHAR_RE = re.compile(r"[\x00-\x1f\x7f-\x9f]")
-SENSITIVE_HOOK_TEXT_RE = re.compile(
-    r"(?i)("
-    r"gh[pousr]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|"
-    r"glpat-[A-Za-z0-9_-]{12,}|(?:AKIA|ASIA)[0-9A-Z]{16}|"
-    r"(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{16,}|"
-    r"sk-(?:ant|proj)-[A-Za-z0-9_-]{8,}|xox[abprs]-[A-Za-z0-9-]{8,}|"
-    r"npm_[A-Za-z0-9]{20,}|AIza[0-9A-Za-z_-]{20,}|"
-    r"SG\.[A-Za-z0-9_-]{16,256}\.[A-Za-z0-9_-]{16,512}|"
-    r"eyJ[A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]*){2}|"
-    r"\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{12,}|"
-    r"[a-z][a-z0-9+.-]{0,31}:/+(?:[^/\s:@]{0,256}:[^/\s@]{0,2048}|[^/\s@]{1,2048})@|"
-    r"(?<![A-Za-z0-9])(?:api[_-]?key|token|secret|password|client[_-]?secret)\s*(?:=|:|%3d)[^/\\\s]{4,})"
-)
-
-
-def hook_text_has_sensitive_evidence(value: str) -> bool:
-    """Return True when hook-visible text contains a high-confidence secret."""
-    return bool(SENSITIVE_HOOK_TEXT_RE.search(value))
-
-
-def hook_label_has_sensitive_evidence(value: str) -> bool:
-    """Return True when a compact hook-visible label must be fully redacted."""
-    return bool(CONTROL_CHAR_RE.search(value) or hook_text_has_sensitive_evidence(value))
-
-
-def redact_sensitive_hook_text(value: str, replacement: str = "[redacted]") -> str:
-    """Redact high-confidence secrets from hook-visible text."""
-    return SENSITIVE_HOOK_TEXT_RE.sub(replacement, value)

package/context-guard-kit/read_symbol.py

@@ -1,483 +0,0 @@
-#!/usr/bin/env python3
-"""Print a symbol-sized slice of a source file instead of the whole file.
-
-This is a deliberately small, dependency-free helper for Claude Code sessions:
-use it after grep/ripgrep identifies a symbol and before asking Claude to read a
-large source file. It is heuristic, not a full language server.
-"""
-from __future__ import annotations
-
-import argparse
-import ast
-import errno
-import hashlib
-import importlib.util
-import json
-import os
-import re
-import stat
-import sys
-from dataclasses import dataclass
-from pathlib import Path
-
-SCRIPT_DIR = Path(__file__).resolve().parent
-
-
-def _load_hook_secret_patterns():
-    searched = []
-    for helper_dir in (SCRIPT_DIR, SCRIPT_DIR.parent / "lib"):
-        helper_path = helper_dir / "hook_secret_patterns.py"
-        searched.append(str(helper_path))
-        if not helper_path.is_file():
-            continue
-        spec = importlib.util.spec_from_file_location("_claude_token_hook_secret_patterns", helper_path)
-        if spec is None or spec.loader is None:
-            continue
-        module = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(module)
-        return module
-    raise ImportError("hook_secret_patterns.py not found in " + ", ".join(searched))
-
-
-_hook_secret_patterns = _load_hook_secret_patterns()
-hook_label_has_sensitive_evidence = _hook_secret_patterns.hook_label_has_sensitive_evidence
-
-DEFAULT_CONTEXT_LINES = 3
-DEFAULT_MAX_CHARS = 16_000
-MAX_CONTEXT_LINES_LIMIT = 200
-MIN_MAX_CHARS = 200
-MAX_CHARS_LIMIT = 200_000
-MAX_READ_BYTES = 2_000_000
-BRACE_FALLBACK_LINES = 80
-PATH_LABEL_MAX_CHARS = 80
-ALLOWED_FIRST_ABSOLUTE_SYMLINKS = {
-    "tmp": Path("/private/tmp"),
-    "var": Path("/private/var"),
-}
-
-
-def bounded_int(value: object, default: int, minimum: int, maximum: int) -> int:
-    try:
-        number = int(value)
-    except (TypeError, ValueError, OverflowError):
-        return default
-    return min(max(number, minimum), maximum)
-
-
-@dataclass
-class SymbolSlice:
-    path: str
-    symbol: str
-    start_line: int
-    end_line: int
-    language: str
-    content: str
-    capped: bool = False
-    scan_truncated: bool = False
-
-    def as_dict(self) -> dict[str, object]:
-        return {
-            "path": self.path,
-            "symbol": self.symbol,
-            "start_line": self.start_line,
-            "end_line": self.end_line,
-            "language": self.language,
-            "content": self.content,
-            "capped": self.capped,
-            "scan_truncated": self.scan_truncated,
-        }
-
-
-def path_label(path: Path, show_paths: bool) -> str:
-    if show_paths:
-        return str(path)
-    digest = hashlib.sha256(str(path).encode("utf-8", "replace")).hexdigest()[:12]
-    raw_name = path.name or "path"
-    name = " ".join(raw_name.strip().split())
-    if hook_label_has_sensitive_evidence(raw_name):
-        name = "redacted-path"
-    elif len(name) > PATH_LABEL_MAX_CHARS:
-        name = name[: PATH_LABEL_MAX_CHARS - 15].rstrip() + "...[truncated]"
-    return f"{name}#path:{digest}"
-
-
-def os_error_summary(exc: OSError) -> str:
-    parts = [exc.__class__.__name__]
-    if getattr(exc, "errno", None) is not None:
-        parts.append(f"errno={exc.errno}")
-    message = " ".join(str(getattr(exc, "strerror", "") or "").strip().split())
-    if message:
-        parts.append(message[:160])
-    return ": ".join(parts)
-
-
-def has_symlink_component(path: Path) -> bool:
-    """Return True when the requested path traverses an explicit symlink."""
-    if path.is_symlink():
-        return True
-    current = Path(path.anchor) if path.is_absolute() else Path()
-    for part in path.parts:
-        if path.is_absolute() and part == path.anchor:
-            continue
-        current = current / part
-        if current.is_symlink():
-            return True
-    return False
-
-
-def _base_open_flags() -> int:
-    flags = os.O_RDONLY
-    if hasattr(os, "O_CLOEXEC"):
-        flags |= os.O_CLOEXEC
-    return flags
-
-
-def _no_follow_flag() -> int:
-    if hasattr(os, "O_NOFOLLOW"):
-        return os.O_NOFOLLOW
-    raise OSError("platform does not support no-follow file opens")
-
-
-def _directory_flag() -> int:
-    return getattr(os, "O_DIRECTORY", 0)
-
-
-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:
-    """Rewrite narrow platform-owned absolute aliases before no-follow traversal."""
-    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 _lstat_at_no_follow(dir_fd: int, component: str, path: Path) -> os.stat_result:
-    if os.stat not in getattr(os, "supports_dir_fd", set()):
-        raise OSError(errno.ENOSYS, "platform does not support directory-relative no-follow stat", str(path))
-    if os.stat not in getattr(os, "supports_follow_symlinks", set()):
-        raise OSError(errno.ENOSYS, "platform does not support no-follow stat", str(path))
-    return os.stat(component, dir_fd=dir_fd, follow_symlinks=False)
-
-
-def _open_directory_at(dir_fd: int, component: str, path: Path) -> int:
-    component_stat = _lstat_at_no_follow(dir_fd, component, path)
-    if stat.S_ISLNK(component_stat.st_mode):
-        raise OSError(errno.ELOOP, "symlink path component", str(path))
-    if not stat.S_ISDIR(component_stat.st_mode):
-        raise OSError(errno.ENOTDIR, "not a directory", str(path))
-    flags = _base_open_flags() | _directory_flag() | _no_follow_flag()
-    fd = os.open(component, flags, dir_fd=dir_fd)
-    try:
-        opened = os.fstat(fd)
-        if not stat.S_ISDIR(opened.st_mode) or not os.path.samestat(component_stat, opened):
-            raise OSError(errno.ELOOP, "path component changed while opening", str(path))
-        return fd
-    except Exception:
-        os.close(fd)
-        raise
-
-
-def _open_regular_no_symlink(path: Path) -> int:
-    """Open a regular file without following symlinks in any trusted component."""
-    if os.open not in os.supports_dir_fd:
-        raise OSError("platform does not support directory-relative no-follow opens")
-    path = _normalize_allowed_first_absolute_symlink(path)
-    nofollow = _no_follow_flag()
-    components = list(path.parts)
-    if path.is_absolute() and components:
-        components = components[1:]
-    if not components:
-        raise OSError(f"not a regular file: {path}")
-
-    root = path.anchor if path.is_absolute() else "."
-    dir_fd = os.open(root or ".", _base_open_flags() | _directory_flag())
-    try:
-        for component in components[:-1]:
-            next_fd = _open_directory_at(dir_fd, component, path)
-            os.close(dir_fd)
-            dir_fd = next_fd
-
-        before = _lstat_at_no_follow(dir_fd, components[-1], path)
-        if stat.S_ISLNK(before.st_mode):
-            raise OSError(errno.ELOOP, "symlink path component", str(path))
-        if not stat.S_ISREG(before.st_mode):
-            raise OSError(errno.EINVAL, "not a regular file", str(path))
-        fd = os.open(components[-1], _base_open_flags() | nofollow, dir_fd=dir_fd)
-        try:
-            opened = os.fstat(fd)
-            if not stat.S_ISREG(opened.st_mode) or not os.path.samestat(before, opened):
-                raise OSError(errno.ELOOP, "path changed while opening", str(path))
-            return fd
-        except Exception:
-            os.close(fd)
-            raise
-    finally:
-        os.close(dir_fd)
-
-
-def read_text_bounded(path: Path) -> tuple[str, bool]:
-    fd = _open_regular_no_symlink(path)
-    try:
-        with os.fdopen(fd, "rb") as handle:
-            fd = -1
-            data = handle.read(MAX_READ_BYTES + 1)
-        truncated = len(data) > MAX_READ_BYTES
-        if truncated:
-            data = data[:MAX_READ_BYTES]
-        return data.decode("utf-8", "replace"), truncated
-    finally:
-        if fd != -1:
-            os.close(fd)
-
-
-def language_for(path: Path) -> str:
-    suffix = path.suffix.lower()
-    if suffix == ".py":
-        return "python"
-    if suffix in {".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"}:
-        return "javascript"
-    if suffix == ".go":
-        return "go"
-    if suffix == ".rs":
-        return "rust"
-    return "generic"
-
-
-def symbol_patterns(symbol: str, language: str) -> list[re.Pattern[str]]:
-    escaped = re.escape(symbol)
-    if language == "python":
-        return [
-            re.compile(rf"^(?P<indent>\s*)(?:async\s+)?def\s+{escaped}\b"),
-            re.compile(rf"^(?P<indent>\s*)class\s+{escaped}\b"),
-        ]
-    if language == "javascript":
-        return [
-            re.compile(rf"^\s*(?:export\s+default\s+)?(?:export\s+)?(?:async\s+)?function\s+{escaped}\b"),
-            re.compile(rf"^\s*(?:export\s+)?class\s+{escaped}\b"),
-            re.compile(rf"^\s*(?:export\s+)?(?:const|let|var)\s+{escaped}\b"),
-            re.compile(rf"^\s*(?:export\s+)?(?:interface|type)\s+{escaped}\b"),
-            re.compile(rf"^\s*(?:(?:public|private|protected|static|async|get|set)\s+)*{escaped}\s*\([^;]*\)\s*(?::[^\{{;]+)?\{{"),
-            re.compile(rf"^\s*{escaped}\s*:\s*(?:async\s+)?(?:function\b|\([^)]*\)\s*=>|[^,]+=>)"),
-        ]
-    if language == "go":
-        return [
-            re.compile(rf"^\s*func\s+(?:\([^)]*\)\s*)?{escaped}\b"),
-            re.compile(rf"^\s*type\s+{escaped}\b"),
-        ]
-    if language == "rust":
-        return [
-            re.compile(rf"^\s*(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?fn\s+{escaped}\b"),
-            re.compile(rf"^\s*(?:pub(?:\([^)]*\))?\s+)?(?:struct|enum|trait|type)\s+{escaped}\b"),
-            re.compile(rf"^\s*impl\b.*\b{escaped}\b"),
-        ]
-    return [re.compile(rf"\b{escaped}\b")]
-
-
-def find_start(lines: list[str], symbol: str, language: str) -> int | None:
-    patterns = symbol_patterns(symbol, language)
-    for index, line in enumerate(lines):
-        if any(pattern.search(line) for pattern in patterns):
-            return index
-    return None
-
-
-def python_block_end(lines: list[str], start: int) -> int:
-    indent = len(lines[start]) - len(lines[start].lstrip())
-    end = start + 1
-    pending_blank_or_comment_end = end
-    for index in range(start + 1, len(lines)):
-        line = lines[index]
-        stripped = line.strip()
-        if not stripped:
-            pending_blank_or_comment_end = index + 1
-            continue
-        current_indent = len(line) - len(line.lstrip())
-        if stripped.startswith("#"):
-            if current_indent > indent:
-                end = index + 1
-            else:
-                pending_blank_or_comment_end = index + 1
-            continue
-        if current_indent <= indent:
-            break
-        end = max(index + 1, pending_blank_or_comment_end)
-    return max(end, start + 1)
-
-
-def python_ast_block_end(text: str, symbol: str, start: int) -> int | None:
-    try:
-        tree = ast.parse(text)
-    except SyntaxError:
-        return None
-    for node in ast.walk(tree):
-        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
-            continue
-        if node.name != symbol or node.lineno - 1 != start:
-            continue
-        end_lineno = getattr(node, "end_lineno", None)
-        if isinstance(end_lineno, int):
-            return max(end_lineno, node.lineno)
-    return None
-
-
-def brace_block_end(lines: list[str], start: int) -> int:
-    depth = 0
-    started = False
-    in_block_comment = False
-    for index in range(start, len(lines)):
-        line, in_block_comment = strip_line_for_brace_count(lines[index], in_block_comment)
-        opens = line.count("{")
-        closes = line.count("}")
-        if opens:
-            started = True
-        depth += opens - closes
-        if started and depth <= 0:
-            return index + 1
-        if not started and index >= start and line.strip().endswith((";", ",")):
-            return index + 1
-    # Heuristic fallback for unmatched braces or deliberately truncated files.
-    return min(len(lines), start + BRACE_FALLBACK_LINES)
-
-
-def strip_line_strings(line: str) -> str:
-    # Good enough for brace counting in source snippets; avoids most braces in strings.
-    line = re.sub(r'"(?:\\.|[^"\\])*"|\'(?:\\.|[^\'\\])*\'', '""', line)
-    line = re.sub(r"`(?:\\.|[^`\\])*`", "``", line)
-    return line
-
-
-def strip_line_for_brace_count(line: str, in_block_comment: bool = False) -> tuple[str, bool]:
-    # Track multi-line block comments so braces inside comments do not end a
-    # JavaScript/Go/Rust symbol slice before the real closing brace.
-    line = strip_line_strings(line)
-    output: list[str] = []
-    index = 0
-    while index < len(line):
-        if in_block_comment:
-            end = line.find("*/", index)
-            if end == -1:
-                return "".join(output), True
-            index = end + 2
-            in_block_comment = False
-            continue
-        line_comment = line.find("//", index)
-        block_comment = line.find("/*", index)
-        if line_comment != -1 and (block_comment == -1 or line_comment < block_comment):
-            output.append(line[index:line_comment])
-            break
-        if block_comment == -1:
-            output.append(line[index:])
-            break
-        output.append(line[index:block_comment])
-        index = block_comment + 2
-        in_block_comment = True
-    return "".join(output), in_block_comment
-
-
-def find_symbol_slice(path: Path, symbol: str, context: int, max_chars: int, show_paths: bool) -> SymbolSlice | None:
-    text, scan_truncated = read_text_bounded(path)
-    lines = text.splitlines(keepends=True)
-    language = language_for(path)
-    start = find_start(lines, symbol, language)
-    if start is None:
-        return None
-
-    if language == "python":
-        end = python_ast_block_end(text, symbol, start) or python_block_end(lines, start)
-    elif language in {"javascript", "go", "rust"}:
-        end = brace_block_end(lines, start)
-    else:
-        end = min(len(lines), start + 40)
-
-    start_with_context = max(0, start - max(0, context))
-    end_with_context = min(len(lines), end + max(0, context))
-    content = "".join(lines[start_with_context:end_with_context])
-    capped = False
-    if max_chars > 0 and len(content) > max_chars:
-        marker = f"\n[context-guard-kit] symbol slice capped: {len(content)} chars total\n"
-        keep = max(0, max_chars - len(marker))
-        content = content[:keep].rstrip() + marker
-        capped = True
-    return SymbolSlice(
-        path_label(path.resolve(), show_paths),
-        symbol,
-        start_with_context + 1,
-        end_with_context,
-        language,
-        content,
-        capped,
-        scan_truncated,
-    )
-
-
-def print_text(result: SymbolSlice) -> None:
-    print(f"[context-guard-kit] {result.path}:{result.start_line}-{result.end_line} symbol={result.symbol} language={result.language}")
-    print(result.content, end="" if result.content.endswith("\n") else "\n")
-    if result.capped:
-        print("[context-guard-kit] rerun with a narrower symbol or larger --max-chars only if necessary.")
-    if result.scan_truncated:
-        print(f"[context-guard-kit] search scanned only the first {MAX_READ_BYTES} bytes of the file.")
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(prog="context-guard-read-symbol")
-    parser.add_argument("path")
-    parser.add_argument("symbol")
-    parser.add_argument("--context", type=int, default=DEFAULT_CONTEXT_LINES)
-    parser.add_argument("--max-chars", type=int, default=DEFAULT_MAX_CHARS)
-    parser.add_argument("--json", action="store_true")
-    parser.add_argument("--show-paths", action="store_true", help="show raw absolute paths in output; local debugging only because private paths may be exposed")
-    args = parser.parse_args()
-
-    args.context = bounded_int(args.context, DEFAULT_CONTEXT_LINES, 0, MAX_CONTEXT_LINES_LIMIT)
-    args.max_chars = bounded_int(args.max_chars, DEFAULT_MAX_CHARS, MIN_MAX_CHARS, MAX_CHARS_LIMIT)
-
-    path = Path(args.path).expanduser()
-    path = _normalize_allowed_first_absolute_symlink(path)
-    safe_path = path_label(path.absolute(), args.show_paths)
-    if has_symlink_component(path):
-        print(f"context-guard-read-symbol: refusing symlink path component: {safe_path}", file=sys.stderr)
-        return 2
-    if not path.is_file():
-        print(f"context-guard-read-symbol: not a file: {safe_path}", file=sys.stderr)
-        return 2
-    try:
-        result = find_symbol_slice(path, args.symbol, args.context, args.max_chars, args.show_paths)
-    except OSError as exc:
-        print(f"context-guard-read-symbol: could not read file safely: {safe_path}: {os_error_summary(exc)}", file=sys.stderr)
-        return 2
-    if result is None:
-        suffix = ""
-        try:
-            if path.stat().st_size > MAX_READ_BYTES:
-                suffix = f" in first {MAX_READ_BYTES} bytes; use rg -n to locate a later match"
-        except OSError:
-            pass
-        print(f"context-guard-read-symbol: symbol not found{suffix}: {args.symbol}", file=sys.stderr)
-        return 1
-    if args.json:
-        print(json.dumps(result.as_dict(), indent=2, sort_keys=True, ensure_ascii=False))
-    else:
-        print_text(result)
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())