claude-dev-env 1.94.0 → 2.0.0

package/hooks/blocking/sensitive_file_protector.py

@@ -1,48 +1,129 @@
 #!/usr/bin/env python3
+"""Deny a Write or Edit whose target filename names a secret or a lock file.
+
+::
+
+    .env              flag: a live secrets file
+    .env.local        flag: a live per-machine secrets file
+    credentials.json  flag: a live credential file
+    id_ed25519        flag: a live private key
+    package-lock.json flag: regenerated by its package manager, never hand-edited
+
+    .env.example      ok: a placeholders-only template, committed on purpose
+    .env.sample       ok: the same shape, .sample spelling
+    .env.template     ok: the same shape, .template spelling
+    main.py           ok: ordinary source
+
+A basename whose FINAL suffix is ``.example``, ``.sample``, or ``.template``
+names a committed template, so the filename guard steps aside for it. The
+suffix has to come last: ``.env.example.bak`` is a copy of a live secrets
+file, not a template, and stays denied.
+
+The guard over a write's contents stays in force: the ``pii_prevention_blocker``
+hook scans what a write carries, so a template holding a real secret or a real
+email address is denied on its contents. The two hooks are layered, and this
+one rules on the filename alone.
+"""
+
+from __future__ import annotations
+
 import fnmatch
 import json
 import os
 import sys
-from pathlib import Path
-
-_hooks_dir = str(Path(__file__).resolve().parent.parent)
-if _hooks_dir not in sys.path:
-    sys.path.insert(0, _hooks_dir)
-
-from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
-
-SENSITIVE_PATTERNS = [
-    ".env",
-    ".env.*",
-    "*.env",
-    "*.pem",
-    "*.key",
-    "*.p12",
-    "*.pfx",
-    "credentials.json",
-    "secrets.json",
-    "id_rsa",
-    "id_ed25519",
-    "package-lock.json",
-    "yarn.lock",
-    "Pipfile.lock",
-    "poetry.lock",
-    "pnpm-lock.yaml",
-    "composer.lock",
-]
-
-WRITE_EDIT_TOOLS = {"Write", "Edit"}
+
+import _path_setup  # noqa: F401
+
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.sensitive_file_protector_constants import (
+    ALL_SENSITIVE_PATTERNS,
+    ALL_TEMPLATE_SUFFIXES,
+    ALL_WRITE_EDIT_TOOLS,
+    DENY_DECISION,
+    DENY_REASON_TEMPLATE,
+    HOOK_EVENT_NAME,
+    HOOK_SCRIPT_NAME,
+)
+
+
+def is_template_filename(filename: str) -> bool:
+    """Report whether a basename names a placeholders-only committed template.
+
+    ::
+
+        .env.example     -> True
+        .ENV.Template    -> True
+        .env.example.bak -> False
+        .env.local       -> False
+
+    Args:
+        filename: The basename of the file a Write or Edit targets.
+
+    Returns:
+        True when the basename's final suffix is a template suffix.
+    """
+    return filename.lower().endswith(ALL_TEMPLATE_SUFFIXES)
 
 
 def is_sensitive_file(file_path: str) -> str | None:
+    """Return the sensitive pattern a path's basename matches, or None.
+
+    Args:
+        file_path: The path the Write or Edit targets.
+
+    Returns:
+        The matched pattern, or None when the basename names a template or
+        matches no pattern.
+    """
     filename = os.path.basename(file_path)
-    for each_pattern in SENSITIVE_PATTERNS:
-        if fnmatch.fnmatch(filename, each_pattern):
+    if is_template_filename(filename):
+        return None
+    for each_pattern in ALL_SENSITIVE_PATTERNS:
+        if fnmatch.fnmatch(filename.lower(), each_pattern.lower()):
             return each_pattern
     return None
 
 
+def build_deny_response(deny_reason: str) -> dict[str, dict[str, str]]:
+    """Wrap a deny reason in the PreToolUse decision payload Claude Code reads.
+
+    Args:
+        deny_reason: The operator-facing sentence explaining the denial.
+
+    Returns:
+        The hook decision dictionary carrying the deny permission decision.
+    """
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": HOOK_EVENT_NAME,
+            "permissionDecision": DENY_DECISION,
+            "permissionDecisionReason": deny_reason,
+        }
+    }
+
+
+def deny_write(file_path: str, matched_pattern: str) -> None:
+    """Record the block in the hook-blocks log and emit the deny decision.
+
+    Args:
+        file_path: The path the Write or Edit targets.
+        matched_pattern: The sensitive pattern the basename matched.
+    """
+    deny_reason = DENY_REASON_TEMPLATE.format(
+        filename=os.path.basename(file_path),
+        matched_pattern=matched_pattern,
+    )
+    log_hook_block(
+        calling_hook_name=HOOK_SCRIPT_NAME,
+        hook_event=HOOK_EVENT_NAME,
+        block_reason=deny_reason,
+        offending_input_preview=file_path,
+    )
+    sys.stdout.write(json.dumps(build_deny_response(deny_reason)))
+
+
 def main() -> None:
+    """Deny the write when the stdin payload targets a sensitive filename."""
     try:
         hook_input = json.load(sys.stdin)
     except json.JSONDecodeError:
@@ -51,7 +132,7 @@ def main() -> None:
     tool_name = hook_input.get("tool_name", "")
     tool_input = hook_input.get("tool_input", {})
 
-    if tool_name not in WRITE_EDIT_TOOLS:
+    if tool_name not in ALL_WRITE_EDIT_TOOLS:
         sys.exit(0)
 
     file_path = tool_input.get("file_path", "")
@@ -59,23 +140,8 @@ def main() -> None:
         sys.exit(0)
 
     matched_pattern = is_sensitive_file(file_path)
-
     if matched_pattern is not None:
-        deny_reason = f"BLOCKED: Sensitive file '{os.path.basename(file_path)}' (pattern: '{matched_pattern}'). Edit manually outside Claude Code."
-        deny_response = {
-            "hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "permissionDecision": "deny",
-                "permissionDecisionReason": deny_reason,
-            }
-        }
-        log_hook_block(
-            calling_hook_name="sensitive_file_protector.py",
-            hook_event="PreToolUse",
-            block_reason=deny_reason,
-            offending_input_preview=file_path,
-        )
-        print(json.dumps(deny_response))
+        deny_write(file_path, matched_pattern)
 
     sys.exit(0)