devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/invariants.py

@@ -0,0 +1,182 @@
+"""
+Sprint 4 – Invariant engine (I1 Information Persistence, I3 Semantic Grounding).
+
+InvariantEngine registers check functions and evaluates them against a context,
+returning actionable InvariantFailure results. ConceptStore persists concept
+definitions with hashes for I3 semantic handshake.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Dict, List, Optional
+
+CONCEPTS_DIR_NAME = "concepts"
+
+
+@dataclass
+class InvariantFailure:
+    """A single invariant violation with an actionable fix hint."""
+    invariant_id: str
+    message: str
+    actionable_fix: str
+
+
+@dataclass
+class InvariantContext:
+    """Context passed to invariant check functions (e.g. for merge or lock-release)."""
+    operation: str  # "merge", "lock_release", "finalize"
+    branch_tips: Optional[Dict[str, str]] = None  # branch -> commit_id
+    concepts_used: Optional[List[str]] = None
+
+
+def _content_hash(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+class ConceptStore:
+    """
+    Persist concept definitions under .GCC/concepts/<name>.json with content hash.
+    I3 semantic grounding requires handshake: operations touching a concept
+    must have a matching definition hash.
+    """
+    def __init__(self, gcc_dir: Path) -> None:
+        self.concepts_dir = gcc_dir / CONCEPTS_DIR_NAME
+
+    def ensure_dir(self) -> None:
+        self.concepts_dir.mkdir(parents=True, exist_ok=True)
+
+    def add(self, name: str, definition: str) -> str:
+        """Store concept definition; return its content hash."""
+        self.ensure_dir()
+        h = _content_hash(definition)
+        path = self.concepts_dir / f"{name}.json"
+        path.write_text(
+            json.dumps({"name": name, "definition": definition, "hash": h}, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        return h
+
+    def get(self, name: str) -> Optional[dict]:
+        """Return {"name", "definition", "hash"} or None."""
+        path = self.concepts_dir / f"{name}.json"
+        if not path.exists():
+            return None
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    def hash_for(self, name: str) -> Optional[str]:
+        """Return stored content hash for concept or None."""
+        obj = self.get(name)
+        return obj.get("hash") if obj else None
+
+    def list_concepts(self) -> List[str]:
+        """Return all concept names."""
+        self.ensure_dir()
+        return [p.stem for p in self.concepts_dir.glob("*.json")]
+
+
+class InvariantEngine:
+    """
+    Register and evaluate invariants. Each invariant is a function
+    (repo, context) -> list[InvariantFailure].
+    """
+    def __init__(self) -> None:
+        self._checkers: List[tuple[str, Callable]] = []
+
+    def register(self, invariant_id: str, check_fn: Callable) -> None:
+        self._checkers.append((invariant_id, check_fn))
+
+    def evaluate(self, repo, context: InvariantContext) -> List[InvariantFailure]:
+        failures: List[InvariantFailure] = []
+        for inv_id, check_fn in self._checkers:
+            try:
+                result = check_fn(repo, context)
+                if result:
+                    failures.extend(result)
+            except Exception as e:
+                failures.append(
+                    InvariantFailure(
+                        inv_id,
+                        str(e),
+                        "Fix the underlying error and re-run the operation.",
+                    )
+                )
+        return failures
+
+
+# --- I1: Information Persistence -------------------------------------------------
+# Decision-finalizing operations must be backed by committed history: the branch
+# tip must exist as a commit object and the decision must be reflected in the event log.
+
+def check_i1_commit_backed(repo, context: InvariantContext) -> List[InvariantFailure]:
+    """
+    I1: Every branch tip in context must exist in commits/ and have a COMMIT event.
+    """
+    if not context.branch_tips:
+        return []
+    failures: List[InvariantFailure] = []
+    commits_dir = repo.gcc_dir / "commits"
+    event_log = repo.gcc_dir / "events.log.jsonl"
+    commit_ids_in_log = set()
+    if event_log.exists():
+        for line in event_log.open("r", encoding="utf-8"):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+                if obj.get("event_type") == "COMMIT":
+                    cid = (obj.get("payload") or {}).get("commit_id")
+                    if cid:
+                        commit_ids_in_log.add(cid)
+            except json.JSONDecodeError:
+                continue
+    for branch, tip in context.branch_tips.items():
+        if not tip:
+            continue
+        commit_path = commits_dir / f"{tip}.json"
+        if not commit_path.exists():
+            failures.append(
+                InvariantFailure(
+                    "I1",
+                    f"Branch '{branch}' tip {tip} has no commit object in .GCC/commits/.",
+                    "Ensure the branch has at least one devtorch commit before merge or lock-release.",
+                )
+            )
+        elif tip not in commit_ids_in_log:
+            failures.append(
+                InvariantFailure(
+                    "I1",
+                    f"Commit {tip} is not recorded in the event log (no COMMIT event).",
+                    "Do not modify .GCC/commits/ or refs manually; use devtorch commit.",
+                )
+            )
+    return failures
+
+
+# --- I3: Semantic Grounding ------------------------------------------------------
+# Operations that touch defined concepts require a handshake: the concept must exist
+# in ConceptStore with a matching hash.
+
+def make_i3_semantic_handshake(concept_store: ConceptStore) -> Callable:
+    """Return a checker that requires all concepts_used to be defined and hash-matched."""
+
+    def check_i3(repo, context: InvariantContext) -> List[InvariantFailure]:
+        if not context.concepts_used:
+            return []
+        failures: List[InvariantFailure] = []
+        for name in context.concepts_used:
+            if concept_store.get(name) is None:
+                failures.append(
+                    InvariantFailure(
+                        "I3",
+                        f"Concept '{name}' has no definition in .GCC/concepts/.",
+                        f"Run: devtorch concept add {name} '<definition>'",
+                    )
+                )
+        return failures
+
+    return check_i3

devtorch_core/mcp/__init__.py

@@ -0,0 +1,10 @@
+"""
+DevTorch MCP server package.
+
+Exposes DevTorch primitives as Model Context Protocol tools that
+Claude Code can call natively.
+"""
+
+from .server import main, find_gcc_repo
+
+__all__ = ["main", "find_gcc_repo"]

devtorch_core/mcp/auth.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import threading
+import time
+from typing import Any, Optional
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+EXEMPT_PATHS = frozenset({"/health", "/readyz"})
+
+
+class APIKeyMiddleware(BaseHTTPMiddleware):
+    """
+    Validates X-DevTorch-Key header against SHA-256 hashes stored in R2
+    at {org_id}/.devtorch/api_keys.json.
+
+    Injects request.state.org_id and request.state.allowed_repos on success.
+    Org is taken from URL path: /{org_id}/{repo_id}/...
+    """
+
+    API_KEYS_KEY = ".devtorch/api_keys.json"
+
+    def __init__(self, app: Any, backend: Any) -> None:
+        super().__init__(app)
+        self._backend = backend
+
+    async def dispatch(self, request: Request, call_next: Any) -> Any:
+        if request.url.path in EXEMPT_PATHS:
+            return await call_next(request)
+        raw_key = request.headers.get("X-DevTorch-Key")
+        if raw_key is None:
+            return JSONResponse({"detail": "Missing X-DevTorch-Key"}, status_code=401)
+
+        key_hash = hashlib.sha256(raw_key.encode()).hexdigest()
+
+        try:
+            data = json.loads(self._backend.read_bytes(self.API_KEYS_KEY))
+        except (FileNotFoundError, json.JSONDecodeError):
+            return JSONResponse({"detail": "Unauthorized"}, status_code=401)
+
+        entry = next(
+            (v for k, v in data.items() if hmac.compare_digest(k, key_hash)),
+            None,
+        )
+        if entry is None:
+            return JSONResponse({"detail": "Unauthorized"}, status_code=401)
+
+        token_org = entry.get("org_id", "")
+        allowed_repos = entry.get("allowed_repos")  # None means all repos
+
+        # Validate org from URL path
+        path_parts = request.url.path.strip("/").split("/")
+        if request.url.path not in EXEMPT_PATHS:
+            if len(path_parts) < 2:
+                return JSONResponse({"detail": "Forbidden"}, status_code=403)
+            url_org, url_repo = path_parts[0], path_parts[1]
+            if url_org != token_org:
+                return JSONResponse({"detail": "Forbidden"}, status_code=403)
+            if allowed_repos is not None and url_repo not in allowed_repos:
+                return JSONResponse({"detail": "Forbidden"}, status_code=403)
+
+        request.state.org_id = token_org
+        request.state.allowed_repos = allowed_repos
+        return await call_next(request)
+
+
+class OAuthMiddleware(BaseHTTPMiddleware):
+    """
+    Validates Authorization: Bearer <jwt> against JWKS endpoints.
+    Supports multiple providers via DEVTORCH_JWKS_URLS (comma-separated).
+    Caches JWKS in memory with a 5-minute TTL.
+    Trusted providers include GitHub Actions OIDC (https://token.actions.githubusercontent.com).
+    """
+
+    CACHE_TTL = 300  # 5 minutes
+
+    def __init__(self, app: Any, jwks_urls: list[str]) -> None:
+        super().__init__(app)
+        self._jwks_urls = jwks_urls
+        self._jwks_cache: dict[str, Any] = {}  # kid → public key
+        self._cache_lock = threading.Lock()
+        self._cache_expiry: float = 0.0
+
+    async def dispatch(self, request: Request, call_next: Any) -> Any:
+        if request.url.path in EXEMPT_PATHS:
+            return await call_next(request)
+
+        auth = request.headers.get("Authorization", "")
+        if not auth.startswith("Bearer "):
+            return JSONResponse({"detail": "Missing Bearer token"}, status_code=401)
+
+        token = auth.removeprefix("Bearer ").strip()
+
+        try:
+            import jwt as _jwt
+            from jwt.exceptions import PyJWTError
+        except ImportError:
+            return JSONResponse({"detail": "Server misconfiguration: PyJWT not installed"}, status_code=500)
+
+        try:
+            header = _jwt.get_unverified_header(token)
+            kid = header.get("kid")
+            key = self._get_key(kid)
+            if key is None:
+                return JSONResponse({"detail": "Unknown key id"}, status_code=401)
+            payload = _jwt.decode(token, key, algorithms=["RS256", "ES256"])
+        except PyJWTError:
+            return JSONResponse({"detail": "Invalid or expired token"}, status_code=401)
+
+        org_id = payload.get("org") or payload.get("https://devtorch.ai/org")
+        if not org_id:
+            return JSONResponse({"detail": "Missing org claim"}, status_code=401)
+
+        path_parts = request.url.path.strip("/").split("/")
+        if len(path_parts) >= 1 and path_parts[0] != org_id:
+            return JSONResponse({"detail": "Forbidden"}, status_code=403)
+
+        request.state.org_id = org_id
+        request.state.user_id = payload.get("sub")
+        return await call_next(request)
+
+    def _get_key(self, kid: Optional[str]) -> Optional[Any]:
+        with self._cache_lock:
+            expiry = self._cache_expiry
+            current_cache = dict(self._jwks_cache)
+
+        # Refresh outside the lock — may be done by multiple threads simultaneously
+        # (idempotent: worst case is a redundant fetch)
+        if time.monotonic() > expiry:
+            new_cache = self._fetch_jwks()
+            if new_cache:
+                with self._cache_lock:
+                    merged = dict(self._jwks_cache)
+                    merged.update(new_cache)
+                    self._jwks_cache = merged
+                    self._cache_expiry = time.monotonic() + self.CACHE_TTL
+                    current_cache = dict(self._jwks_cache)
+            else:
+                # Back off 30s before next attempt to avoid thundering herd
+                with self._cache_lock:
+                    self._cache_expiry = time.monotonic() + 30
+
+        return current_cache.get(kid) if kid else None
+
+    def _fetch_jwks(self) -> dict[str, Any]:
+        """Fetch all JWKS URLs and return a dict of kid → public_key. Returns empty dict on total failure."""
+        import urllib.request
+        import json as _json
+
+        new_cache: dict[str, Any] = {}
+        for url in self._jwks_urls:
+            try:
+                with urllib.request.urlopen(url, timeout=5) as resp:
+                    data = _json.loads(resp.read())
+                for jwk in data.get("keys", []):
+                    try:
+                        key = self._jwk_to_public_key(jwk)
+                        new_cache[jwk["kid"]] = key
+                    except Exception:
+                        pass
+            except Exception:
+                pass  # keep going, try next URL
+        return new_cache
+
+    @staticmethod
+    def _jwk_to_public_key(jwk: dict) -> Any:
+        from jwt.algorithms import RSAAlgorithm, ECAlgorithm
+        import json as _json
+        alg = jwk.get("kty", "RSA")
+        if alg == "RSA":
+            return RSAAlgorithm.from_jwk(_json.dumps(jwk))
+        return ECAlgorithm.from_jwk(_json.dumps(jwk))