toolgraph 0.0.1__py3-none-any.whl

toolgraph/__init__.py

@@ -0,0 +1,3 @@
+"""toolgraph — graph-native MCP/tool registry for advisory governance analysis."""
+
+__version__ = "0.0.1"

toolgraph/artifact_safety.py

@@ -0,0 +1,97 @@
+"""Evidence-only scrubbing and immutable artifact identity validation."""
+
+import re
+from urllib.parse import urlsplit, urlunsplit
+
+_URI = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*://[^\s)]+")
+
+
+def _redact_uri(value: str) -> str:
+    """Remove URI userinfo and query strings without changing ordinary text."""
+    if "://" not in value:
+        return value
+    parts = urlsplit(value)
+    # Use the original netloc rather than ``parts.hostname``: urlsplit
+    # lowercases hostname accessors, while graph resource identity preserves
+    # the authored case. Only userinfo and query data are sensitive here.
+    host = parts.netloc.rsplit("@", 1)[-1]
+    return urlunsplit((parts.scheme, host, parts.path, "", ""))
+
+
+_MAX_REDACT_DEPTH = 100
+
+
+def redact(value, *, _depth: int = 0):
+    """Recursively scrub strings that may contain resource URI credentials."""
+    if _depth > _MAX_REDACT_DEPTH:
+        raise ValueError(
+            f"artifact nesting exceeds the {_MAX_REDACT_DEPTH}-level redaction limit"
+        )
+    if isinstance(value, dict):
+        return {key: redact(item, _depth=_depth + 1) for key, item in value.items()}
+    if isinstance(value, list):
+        return [redact(item, _depth=_depth + 1) for item in value]
+    if isinstance(value, str):
+        # Evidence paths contain a URI inside surrounding graph notation.
+        return _URI.sub(lambda match: _redact_uri(match.group(0)), value)
+    return value
+
+
+_CREDENTIAL_URI = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*://[^/\s:@]+:[^/\s@]+@")
+_CREDENTIAL_QUERY = re.compile(
+    r"[?&](?:api[_-]?key|password|secret|token)=[^&#\s]+", re.IGNORECASE
+)
+
+
+def validate_identity(value: str) -> None:
+    if _CREDENTIAL_URI.search(value) or _CREDENTIAL_QUERY.search(value):
+        raise ValueError("artifact identity contains credential-shaped data")
+
+
+_EVIDENCE_FIELDS = frozenset(
+    {
+        "paths",
+        "deny_paths",
+        "current_paths",
+        "evidence",
+        "resource",
+        "resource_uri",
+        "exception_reason",
+    }
+)
+_IDENTITY_FIELDS = frozenset(
+    {
+        "agent",
+        "principal",
+        "principal_id",
+        "run_id",
+        "candidate",
+        "tool_key",
+        "eligible",
+        "candidates",
+    }
+)
+
+
+def safe_artifact(value, *, _depth=0):
+    """Preserve opaque identities; scrub only explicitly designated evidence."""
+    if _depth > _MAX_REDACT_DEPTH:
+        raise ValueError("artifact nesting exceeds safety limit")
+    if isinstance(value, dict):
+        result = {}
+        for key, item in value.items():
+            if key in _EVIDENCE_FIELDS:
+                result[key] = redact(item)
+                continue
+            if key in _IDENTITY_FIELDS:
+                if isinstance(item, str):
+                    validate_identity(item)
+                elif isinstance(item, list):
+                    for identity in item:
+                        if isinstance(identity, str):
+                            validate_identity(identity)
+            result[key] = safe_artifact(item, _depth=_depth + 1)
+        return result
+    if isinstance(value, list):
+        return [safe_artifact(item, _depth=_depth + 1) for item in value]
+    return value

toolgraph/artifacts.py

@@ -0,0 +1,122 @@
+"""Canonical, private, atomic artifact helpers."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+import errno
+import hashlib
+import json
+import os
+from pathlib import Path
+import tempfile
+import warnings
+
+
+class ArtifactDurabilityWarning(RuntimeWarning):
+    """The artifact was replaced, but crash durability could not be confirmed."""
+
+
+def rfc3339_offset_error(created_at: datetime) -> str | None:
+    """Why *created_at* cannot be stamped on an artifact, or None if it can.
+
+    Returned rather than raised so each producer keeps its own error type.
+    Aware means ``utcoffset()`` returns a value, not merely that tzinfo is
+    set: a tzinfo whose ``utcoffset()`` is None still isoformat()s without an
+    offset, which the schemas' RFC 3339 prose forbids.
+    """
+    offset = created_at.utcoffset()
+    if offset is None:
+        return (
+            "created_at must be timezone-aware — the contract requires an"
+            " RFC 3339 timestamp with a UTC offset"
+        )
+    if offset % timedelta(minutes=1):
+        return (
+            f"created_at offset {offset} has sub-minute resolution — RFC 3339"
+            " offsets are ±HH:MM"
+        )
+    return None
+
+
+def canonical_json_bytes(value: object) -> bytes:
+    """Encode one artifact deterministically for exact-byte digests."""
+    return (
+        json.dumps(
+            value,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+        + "\n"
+    ).encode("utf-8")
+
+
+def sha256_bytes(payload: bytes) -> str:
+    return hashlib.sha256(payload).hexdigest()
+
+
+def fsync_parent_dir(path: Path) -> None:
+    """Make an atomic rename durable on filesystems that support dir fsync.
+
+    Filesystems that cannot fsync a directory (some network/container mounts)
+    report EINVAL/ENOTSUP/EROFS — those are tolerated silently because there
+    is nothing more the writer can do. Any other failure propagates so the
+    caller can decide whether it is fatal (the rename itself already
+    published the file).
+    """
+    if os.name == "nt":  # pragma: no cover - Windows has no directory fd
+        return
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    try:
+        descriptor = os.open(path.parent, flags)
+        try:
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+    except OSError as exc:
+        unsupported = {
+            errno.EINVAL,
+            errno.ENOTSUP,
+            getattr(errno, "EOPNOTSUPP", errno.ENOTSUP),
+            errno.EROFS,
+        }
+        if exc.errno not in unsupported:
+            raise
+
+
+def atomic_write_private(path: Path, payload: bytes) -> str:
+    """Write 0600 bytes via fsync + atomic replace; return exact digest."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary: str | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="wb",
+            dir=path.parent,
+            prefix=f".{path.name}.",
+            delete=False,
+        ) as handle:
+            temporary = handle.name
+            os.chmod(temporary, 0o600)
+            handle.write(payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+        temporary = None
+        os.chmod(path, 0o600)
+        try:
+            fsync_parent_dir(path)
+        except OSError:
+            # The artifact is already atomically visible with the digest the
+            # caller reports. Failing the whole write here would report ERROR
+            # for a correct published file; surface only the narrower
+            # crash-durability uncertainty.
+            warnings.warn(
+                "artifact was replaced, but parent-directory fsync failed; the"
+                " file is published but crash durability is uncertain",
+                ArtifactDurabilityWarning,
+                stacklevel=2,
+            )
+    finally:
+        if temporary is not None:
+            Path(temporary).unlink(missing_ok=True)
+    return sha256_bytes(payload)