clean-room-skill 0.1.0

package/hooks/deny-contaminated-clean-write.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Enforce clean-room write roots for contaminated and clean roles."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+CONTAMINATED_ROLES = {"contaminated-manager-verifier", "contaminated-source-analyst"}
+CLEAN_ROLES = {"clean-architect", "clean-qa-editor"}
+
+
+def load_payload() -> dict:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        return {}
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def configured_roots(name: str) -> list[Path]:
+    value = os.environ.get(name, "")
+    roots = []
+    for item in value.split(os.pathsep):
+        if item:
+            roots.append(Path(item).expanduser().resolve())
+    return roots
+
+
+def candidate_paths(payload: dict) -> list[Path]:
+    tool_input = payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        tool_input = {}
+    values = []
+    for key in ("file_path", "path", "cwd"):
+        value = tool_input.get(key) or payload.get(key)
+        if isinstance(value, str):
+            values.append(value)
+    paths = []
+    for value in values:
+        try:
+            paths.append(Path(value).expanduser().resolve())
+        except OSError:
+            continue
+    return paths
+
+
+def is_under(path: Path, root: Path) -> bool:
+    return path == root or root in path.parents
+
+
+def main() -> int:
+    role = os.environ.get("CLEAN_ROOM_ROLE", "")
+    if role not in CONTAMINATED_ROLES and role not in CLEAN_ROLES:
+        return 0
+    paths = candidate_paths(load_payload())
+    if not paths:
+        print(
+            f"clean-room policy denied role {role} write with no resolved path",
+            file=sys.stderr,
+        )
+        return 1
+
+    source_roots = configured_roots("CLEAN_ROOM_SOURCE_ROOTS")
+    clean_roots = configured_roots("CLEAN_ROOM_CLEAN_ROOTS")
+    contaminated_artifact_roots = configured_roots("CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS")
+
+    if role in CLEAN_ROLES:
+        allowed_read_roots = configured_roots("CLEAN_ROOM_ALLOWED_READ_ROOTS")
+        for path in paths:
+            if any(is_under(path, root) for root in source_roots):
+                print(
+                    f"clean-room policy denied clean role {role} writing source path {path}",
+                    file=sys.stderr,
+                )
+                return 1
+            if any(is_under(path, root) for root in allowed_read_roots) and not any(
+                is_under(path, root) for root in clean_roots
+            ):
+                print(
+                    f"clean-room policy denied clean role {role} writing read-only allowed-read path {path}",
+                    file=sys.stderr,
+                )
+                return 1
+            if not clean_roots:
+                print(
+                    f"clean-room policy denied clean role {role} writing {path}: no clean write roots configured",
+                    file=sys.stderr,
+                )
+                return 1
+            if not any(is_under(path, root) for root in clean_roots):
+                print(
+                    f"clean-room policy denied clean role {role} writing outside clean roots: {path}",
+                    file=sys.stderr,
+                )
+                return 1
+        return 0
+
+    for path in paths:
+        if any(is_under(path, root) for root in clean_roots):
+            print(
+                f"clean-room policy denied contaminated role {role} writing clean path {path}",
+                file=sys.stderr,
+            )
+            return 1
+        if any(is_under(path, root) for root in source_roots):
+            print(
+                f"clean-room policy denied contaminated role {role} writing source path {path}",
+                file=sys.stderr,
+            )
+            return 1
+        if not contaminated_artifact_roots:
+            print(
+                f"clean-room policy denied contaminated role {role} writing {path}: no contaminated artifact roots configured",
+                file=sys.stderr,
+            )
+            return 1
+        if not any(is_under(path, root) for root in contaminated_artifact_roots):
+            print(
+                f"clean-room policy denied contaminated role {role} writing outside contaminated artifact roots: {path}",
+                file=sys.stderr,
+            )
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/hooks.json

@@ -0,0 +1,44 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Shell",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 hooks/clean-room-hook.py --mode safe --check require-clean-room-env.py --check deny-clean-room-shell.py"
+          }
+        ]
+      },
+      {
+        "matcher": "Read|Glob|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 hooks/clean-room-hook.py --mode safe --check require-clean-room-env.py --check deny-clean-source-read.py"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 hooks/clean-room-hook.py --mode safe --check require-clean-room-env.py --check deny-contaminated-clean-write.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 hooks/clean-room-hook.py --mode safe --check require-clean-room-env.py --check check-artifact-leakage.py --check validate-json-schema.py --check validate-handoff-package.py"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/require-clean-room-env.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Require explicit clean-room role and root configuration before tool use."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from clean_room_paths import paths_overlap
+
+
+ROLES = {
+    "contaminated-manager-verifier",
+    "contaminated-source-analyst",
+    "clean-architect",
+    "clean-qa-editor",
+}
+CLEAN_ROLES = {"clean-architect", "clean-qa-editor"}
+NONEMPTY_VARS = (
+    "CLEAN_ROOM_ROLE",
+    "CLEAN_ROOM_SOURCE_ROOTS",
+    "CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS",
+    "CLEAN_ROOM_CLEAN_ROOTS",
+    "CLEAN_ROOM_SCHEMA_DIR",
+)
+ROOT_VARS = (
+    "CLEAN_ROOM_SOURCE_ROOTS",
+    "CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS",
+    "CLEAN_ROOM_CLEAN_ROOTS",
+    "CLEAN_ROOM_SCHEMA_DIR",
+    "CLEAN_ROOM_ALLOWED_READ_ROOTS",
+)
+
+
+def split_roots(value: str) -> list[str]:
+    return [item for item in value.split(os.pathsep) if item]
+
+
+def validate_roots(name: str, require_existing: bool = False) -> list[str]:
+    value = os.environ.get(name, "")
+    errors = []
+    if name in NONEMPTY_VARS and not split_roots(value):
+        errors.append(f"{name} must not be empty")
+        return errors
+    for item in split_roots(value):
+        try:
+            path = Path(item).expanduser().resolve()
+        except OSError as exc:
+            errors.append(f"{name} has invalid path {item!r}: {exc}")
+            continue
+        if require_existing and not path.exists():
+            errors.append(f"{name} path does not exist: {path}")
+    return errors
+
+
+def resolved_roots(name: str) -> tuple[list[Path], list[str]]:
+    roots: list[Path] = []
+    errors: list[str] = []
+    for item in split_roots(os.environ.get(name, "")):
+        try:
+            roots.append(Path(item).expanduser().resolve())
+        except OSError as exc:
+            errors.append(f"{name} has invalid path {item!r}: {exc}")
+    return roots, errors
+
+
+def reject_overlaps(left_name: str, right_name: str, message: str) -> list[str]:
+    left_roots, left_errors = resolved_roots(left_name)
+    right_roots, right_errors = resolved_roots(right_name)
+    errors = left_errors + right_errors
+    for left in left_roots:
+        for right in right_roots:
+            if paths_overlap(left, right):
+                errors.append(f"{message}: {left_name}={left} overlaps {right_name}={right}")
+    return errors
+
+
+def main() -> int:
+    role = os.environ.get("CLEAN_ROOM_ROLE", "")
+    missing = [name for name in NONEMPTY_VARS if name not in os.environ]
+    errors = [f"{name} is not set" for name in missing]
+    if role and role not in ROLES:
+        errors.append(f"CLEAN_ROOM_ROLE must be one of {', '.join(sorted(ROLES))}")
+    for name in ROOT_VARS:
+        if name in os.environ:
+            errors.extend(validate_roots(name, require_existing=name == "CLEAN_ROOM_SCHEMA_DIR"))
+    if role in CLEAN_ROLES and "CLEAN_ROOM_ALLOWED_READ_ROOTS" not in os.environ:
+        errors.append("CLEAN_ROOM_ALLOWED_READ_ROOTS is not set for clean role")
+    errors.extend(
+        reject_overlaps(
+            "CLEAN_ROOM_SOURCE_ROOTS",
+            "CLEAN_ROOM_CLEAN_ROOTS",
+            "source roots and clean roots must be separate",
+        )
+    )
+    errors.extend(
+        reject_overlaps(
+            "CLEAN_ROOM_SOURCE_ROOTS",
+            "CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS",
+            "source roots and contaminated artifact roots must be separate",
+        )
+    )
+    errors.extend(
+        reject_overlaps(
+            "CLEAN_ROOM_CLEAN_ROOTS",
+            "CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS",
+            "clean roots and contaminated artifact roots must be separate",
+        )
+    )
+    errors.extend(
+        reject_overlaps(
+            "CLEAN_ROOM_ALLOWED_READ_ROOTS",
+            "CLEAN_ROOM_SOURCE_ROOTS",
+            "allowed clean read roots must not expose source roots",
+        )
+    )
+    if errors:
+        print("clean-room environment check failed:", file=sys.stderr)
+        for error in errors:
+            print(f"  {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/validate-handoff-package.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Verify clean-room handoff package paths and hashes."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from clean_room_paths import checked_write_paths, env_roots, load_payload, path_is_under
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def is_handoff_package(path: Path, data: object) -> bool:
+    if not isinstance(data, dict):
+        return False
+    return (
+        path.name == "handoff-package.json"
+        or data.get("package_id") is not None
+        or (
+            data.get("from_domain") == "contaminated"
+            and data.get("to_domain") == "clean"
+            and isinstance(data.get("artifacts"), list)
+        )
+    )
+
+
+def resolve_artifact_path(raw_path: str, clean_roots: list[Path]) -> tuple[Path | None, list[str]]:
+    errors: list[str] = []
+    path = Path(raw_path).expanduser()
+    if path.is_absolute():
+        resolved = path.resolve()
+        if not any(path_is_under(resolved, root) for root in clean_roots):
+            errors.append(f"artifact path is outside CLEAN_ROOM_CLEAN_ROOTS: {resolved}")
+        return resolved, errors
+
+    matches = [(root / path).resolve() for root in clean_roots if (root / path).is_file()]
+    if len(matches) > 1:
+        errors.append(f"artifact path is ambiguous across clean roots: {raw_path}")
+        return None, errors
+    if matches:
+        return matches[0], errors
+    if not clean_roots:
+        errors.append("CLEAN_ROOM_CLEAN_ROOTS must be set to verify handoff artifacts")
+        return None, errors
+    return (clean_roots[0] / path).resolve(), errors
+
+
+def validate_artifact(
+    item: Any,
+    clean_roots: list[Path],
+    blocked_roots: list[Path],
+) -> list[str]:
+    errors: list[str] = []
+    if not isinstance(item, dict):
+        return ["handoff artifact entry must be an object"]
+    raw_path = item.get("path")
+    if not isinstance(raw_path, str) or not raw_path:
+        return ["handoff artifact path must be a non-empty string"]
+    if Path(raw_path).name == "source-index.json" or item.get("artifact_type") == "source-index":
+        errors.append("source-index.json must not be included in a clean handoff package")
+
+    artifact_path, path_errors = resolve_artifact_path(raw_path, clean_roots)
+    errors.extend(path_errors)
+    if artifact_path is None:
+        return errors
+    if not any(path_is_under(artifact_path, root) for root in clean_roots):
+        errors.append(f"artifact path is outside CLEAN_ROOM_CLEAN_ROOTS: {artifact_path}")
+    if any(path_is_under(artifact_path, root) for root in blocked_roots):
+        errors.append(f"artifact path points into a contaminated or source root: {artifact_path}")
+    if not artifact_path.is_file():
+        errors.append(f"referenced artifact does not exist: {artifact_path}")
+        return errors
+
+    expected_sha = item.get("sha256")
+    if not isinstance(expected_sha, str) or len(expected_sha) != 64:
+        errors.append(f"artifact sha256 must be a 64-character hex string: {raw_path}")
+        return errors
+    actual_sha = sha256_file(artifact_path)
+    if actual_sha.lower() != expected_sha.lower():
+        errors.append(f"artifact sha256 mismatch for {artifact_path}")
+    return errors
+
+
+def validate_handoff(path: Path) -> list[str]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return [f"JSON parse failed for {path}: {exc}"]
+    if not is_handoff_package(path, data):
+        return []
+    if not isinstance(data, dict):
+        return [f"handoff package must be an object: {path}"]
+
+    clean_roots = env_roots("CLEAN_ROOM_CLEAN_ROOTS")
+    blocked_roots = env_roots("CLEAN_ROOM_SOURCE_ROOTS") + env_roots("CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS")
+    artifacts = data.get("artifacts")
+    if not isinstance(artifacts, list):
+        return [f"handoff package artifacts must be an array: {path}"]
+    errors: list[str] = []
+    for item in artifacts:
+        errors.extend(validate_artifact(item, clean_roots, blocked_roots))
+    return errors
+
+
+def main() -> int:
+    payload, payload_error = load_payload()
+    if payload_error:
+        print(f"clean-room handoff integrity failed: {payload_error}", file=sys.stderr)
+        return 1
+    paths, path_errors = checked_write_paths(payload, "clean-room handoff integrity")
+    if path_errors:
+        for error in path_errors:
+            print(f"clean-room handoff integrity failed: {error}", file=sys.stderr)
+        return 1
+    for path in paths:
+        if path.suffix.lower() != ".json" or not path.is_file():
+            continue
+        errors = validate_handoff(path)
+        if errors:
+            print(f"clean-room handoff integrity failed for {path}:", file=sys.stderr)
+            for error in errors[:20]:
+                print(f"  {error}", file=sys.stderr)
+            if len(errors) > 20:
+                print(f"  ... {len(errors) - 20} more error(s)", file=sys.stderr)
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())