@heretek-ai/epistemic-swarm 0.4.7 → 0.4.8

package/runner/mcp_server.py

@@ -63,6 +63,13 @@ def _capture_stdout(fn: Callable[..., Any], *args: Any, **kwargs: Any) -> str:
 # tool handlers
 # ---------------------------------------------------------------------------
 
+DEFAULT_RESEARCH_DIR = ".research"
+
+
+def _resolve_base_dir(args: Dict[str, Any]) -> Path:
+    raw = args.get("base_dir") or args.get("dir") or DEFAULT_RESEARCH_DIR
+    return Path(os.path.realpath(str(raw)))
+
 def _handle_config(args: Dict[str, Any]) -> str:
     """Inspect or modify swarm parameters in .research/config.json."""
     from skills.swarm_config.configure import (
@@ -71,7 +78,7 @@ def _handle_config(args: Dict[str, Any]) -> str:
         save_config,
     )
 
-    base_dir = args.get("base_dir") or args.get("dir") or ".research"
+    base_dir = str(_resolve_base_dir(args))
     cfg = load_config(base_dir)
 
     updates = {}
@@ -102,7 +109,7 @@ def _run_swarm_mode(mode: Optional[str], args: Dict[str, Any]) -> str:
 
     frontier = args.get("frontier") or args.get("frontier_file")
     runner = SwarmRunner(
-        base_dir=Path(args.get("base_dir") or args.get("dir") or ".research"),
+        base_dir=_resolve_base_dir(args),
         mock_mode=bool(args.get("mock_claude") or args.get("mock_mode")),
         mode=mode or args.get("mode"),
         engine=args.get("engine"),
@@ -155,7 +162,7 @@ def _handle_verify_quote(args: Dict[str, Any]) -> str:
     if not content_hash or quote is None:
         raise ValueError("hash and quote are required")
 
-    hasher = SourceHasher(Path(args.get("base_dir") or args.get("dir") or ".research"))
+    hasher = SourceHasher(_resolve_base_dir(args))
     is_verified, confidence, message = hasher.verify_quote(content_hash, quote)
     return _tool_text({
         "verified": bool(is_verified),
@@ -173,7 +180,7 @@ def _handle_report_retraction(args: Dict[str, Any]) -> str:
     event = args.get("event")
     if not source_hash or not event:
         raise ValueError("hash and event are required")
-    base_dir = Path(args.get("base_dir") or args.get("dir") or ".research")
+    base_dir = _resolve_base_dir(args)
     path = write_retraction(
         base_dir,
         source_hash,
@@ -188,7 +195,7 @@ def _handle_check_staleness(args: Dict[str, Any]) -> str:
     """Run one claim-degradation pass (retractions -> STALE/SUSPECT + requeue)."""
     from runner.living_dossiers import check_staleness
 
-    base_dir = Path(args.get("base_dir") or args.get("dir") or ".research")
+    base_dir = _resolve_base_dir(args)
     scope_ids = args.get("scope_ids")
     return _tool_text(check_staleness(base_dir, scope_ids=scope_ids))
 
@@ -202,7 +209,7 @@ def _handle_set_domain_pack(args: Dict[str, Any]) -> str:
     if not pack:
         raise ValueError("pack is required")
     constitution = load_domain_pack(pack)  # raises if unknown — fail loudly
-    base_dir = args.get("base_dir") or args.get("dir") or ".research"
+    base_dir = str(_resolve_base_dir(args))
     cfg = load_config(base_dir)
     cfg["domain_pack"] = pack
     save_config(cfg, base_dir)
@@ -219,7 +226,7 @@ def _handle_export_brief(args: Dict[str, Any]) -> str:
     """Export a proof-carrying research brief (signed, self-contained bundle)."""
     from runner.pcrb import export_brief
 
-    base_dir = Path(args.get("base_dir") or args.get("dir") or ".research")
+    base_dir = _resolve_base_dir(args)
     key = args.get("key")
     key_path = Path(args["key_file"]) if args.get("key_file") else None
     path = export_brief(
@@ -244,7 +251,7 @@ def _handle_verify_brief(args: Dict[str, Any]) -> str:
     brief = args.get("brief") or args.get("path")
     if not brief:
         raise ValueError("brief path is required")
-    p = Path(brief)
+    p = Path(os.path.realpath(str(brief)))
     if not p.exists():
         raise FileNotFoundError(f"no such brief: {p}")
     bundle = json.loads(p.read_text(encoding="utf-8"))
@@ -252,8 +259,13 @@ def _handle_verify_brief(args: Dict[str, Any]) -> str:
     key = None
     if args.get("key"):
         key = args["key"].encode("utf-8")
-    elif args.get("key_file") and Path(args["key_file"]).exists():
-        key = Path(args["key_file"]).read_bytes().strip()
+    elif args.get("key_file"):
+        kf = Path(os.path.realpath(str(args["key_file"])))
+        # An explicit key_file that cannot be read must surface as an error, not
+        # a silent fallthrough to `alg: "none"`.
+        if not kf.is_file():
+            raise ValueError(f"key file is not a readable file: {args['key_file']!r}")
+        key = kf.read_bytes().strip()
     elif os.environ.get(ENV_KEY):
         key = os.environ[ENV_KEY].encode("utf-8")
 
@@ -264,7 +276,7 @@ def _handle_reindex_claims(args: Dict[str, Any]) -> str:
     """Rebuild the derived claims.sqlite index from .research flat files."""
     from runner.claim_store import reindex
 
-    base_dir = Path(args.get("base_dir") or args.get("dir") or ".research")
+    base_dir = _resolve_base_dir(args)
     return _tool_text(reindex(base_dir))
 
 

package/runner/path_safety.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Canonical path safety and containment helpers.
+
+Trust boundary
+--------------
+These helpers exist for the real S8707 pattern: an **untrusted relative segment
+joined under a trusted base** (a cache key, a scope id, a filename from an LLM).
+That is where containment must be enforced.
+
+They are deliberately *not* applied to caller-chosen CLI/tool arguments such as
+``pcrb --out``, ``socratic_tree --file`` or ``--key-file``. Those are the
+principal's own paths: the user (or the orchestrating agent) is the trust root,
+and restricting them would break legitimate use like writing a brief to
+``~/reports/``. Those sites canonicalise with ``os.path.realpath`` only. Do not
+"tighten" them by routing through :func:`safe_resolve_path` — that is a behavior
+change, not a hardening.
+"""
+
+import os
+from pathlib import Path
+from typing import Union
+
+
+def safe_resolve_path(untrusted_path: Union[str, Path], base_dir: Union[str, Path]) -> Path:
+    """Canonicalise a path and require that it stays inside ``base_dir``.
+
+    Accepts either an absolute path or one relative to ``base_dir``. An absolute
+    path is allowed only when it already resolves inside the base; ``..``
+    segments and symlinks are resolved *before* the containment test, so neither
+    can be used to escape.
+
+    Raises ValueError if the resolved path escapes ``base_dir``.
+    """
+    base = os.path.realpath(str(base_dir))
+    raw = str(untrusted_path)
+    # os.path.join would silently drop `base` for an absolute second argument,
+    # so decide the candidate explicitly.
+    candidate = raw if os.path.isabs(raw) else os.path.join(base, raw)
+    target = os.path.realpath(candidate)
+    base_prefix = base if base.endswith(os.sep) else base + os.sep
+    if target != base and not target.startswith(base_prefix):
+        raise ValueError(f"Path traversal detected: {untrusted_path!r} escapes {base_dir!r}")
+    return Path(target)
+
+
+def safe_join(base_dir: Union[str, Path], *segments: str) -> Path:
+    """Join untrusted *relative* segments under a trusted base, with containment.
+
+    This is the S8707 shape: ``base_dir / f"{user_token}.md"``. Each segment must
+    be a bare name — no separators, no ``..`` — and the joined result must still
+    resolve inside ``base_dir``.
+
+    Raises ValueError on any segment that could escape.
+    """
+    for segment in segments:
+        if not segment or segment in (".", ".."):
+            raise ValueError(f"Unsafe path segment: {segment!r}")
+        if os.sep in segment or (os.altsep and os.altsep in segment):
+            raise ValueError(f"Path separator in segment: {segment!r}")
+        if Path(segment).name != segment:
+            raise ValueError(f"Unsafe path segment: {segment!r}")
+    return safe_resolve_path(os.path.join(*segments), base_dir)

package/runner/pcrb.py

@@ -70,8 +70,16 @@ def _resolve_key(key: Optional[str], key_path: Optional[Path]) -> Optional[bytes
     env = os.environ.get(ENV_KEY)
     if env:
         return env.encode("utf-8")
-    if key_path and Path(key_path).exists():
-        return Path(key_path).read_bytes().strip()
+    if key_path:
+        # An explicitly supplied key file that cannot be read must fail loudly.
+        # Returning None here would sign the brief with `alg: "none"` and report
+        # success — a typo'd path silently produces an unauthenticated bundle.
+        canonical_key_path = Path(os.path.realpath(str(key_path)))
+        if not canonical_key_path.is_file():
+            raise ValueError(
+                f"key file is not a readable file: {key_path!r} (resolved {canonical_key_path})"
+            )
+        return canonical_key_path.read_bytes().strip()
     return None
 
 
@@ -82,40 +90,19 @@ def sign_manifest(manifest: Dict[str, Any], key: Optional[bytes], key_id: str =
     return {"alg": "hmac-sha256", "key_id": key_id, "sig": sig}
 
 
-def export_brief(
-    base_dir: Path,
-    out_path: Optional[Path] = None,
-    scope_ids: Optional[List[str]] = None,
-    objective: Optional[str] = None,
-    key: Optional[str] = None,
-    key_path: Optional[Path] = None,
-    key_id: str = "local",
-) -> Path:
-    """Assemble a PCRB from a .research workspace. Returns the bundle path."""
-    from skills.research_cache.hasher import SourceHasher
-
-    base_dir = Path(base_dir)
-    hasher = SourceHasher(base_dir)
-
-    # --- synthesis ---
-    synthesis = ""
+def _resolve_synthesis(base_dir: Path) -> str:
     final_md = base_dir / "final_synthesis.md"
     if final_md.exists():
-        synthesis = final_md.read_text(encoding="utf-8")
-    else:
-        parts = sorted((base_dir / "scratchpads").glob("*/scope_synthesis.md"))
-        synthesis = "\n\n---\n\n".join(p.read_text(encoding="utf-8") for p in parts)
+        return final_md.read_text(encoding="utf-8")
+    parts = sorted((base_dir / "scratchpads").glob("*/scope_synthesis.md"))
+    return "\n\n---\n\n".join(p.read_text(encoding="utf-8") for p in parts)
 
-    # --- claims + witnesses ---
-    scratch = base_dir / "scratchpads"
-    scope_dirs = (
-        [scratch / s for s in scope_ids]
-        if scope_ids
-        else (sorted(p for p in scratch.iterdir() if p.is_dir()) if scratch.exists() else [])
-    )
+
+def _collect_claims(
+    scope_dirs: List[Path], hasher: Any
+) -> Tuple[List[Dict[str, Any]], set]:
     claim_records: List[Dict[str, Any]] = []
     needed_hashes = set()
-
     for scope_dir in scope_dirs:
         for dossier_name in ("alpha_dossier.json", "beta_dossier.json"):
             dpath = scope_dir / dossier_name
@@ -140,6 +127,46 @@ def export_brief(
                     needed_hashes.add(c.source_hash)
                 rec["witness"] = witness
                 claim_records.append(rec)
+    return claim_records, needed_hashes
+
+
+def _resolve_objective(base_dir: Path, objective: Optional[str]) -> Optional[str]:
+    if objective:
+        return objective
+    manifest_p = base_dir / "manifest.json"
+    if manifest_p.exists():
+        try:
+            return json.loads(manifest_p.read_text(encoding="utf-8")).get("objective")
+        except (OSError, json.JSONDecodeError):
+            return None
+    return None
+
+
+def export_brief(
+    base_dir: Path,
+    out_path: Optional[Path] = None,
+    scope_ids: Optional[List[str]] = None,
+    objective: Optional[str] = None,
+    key: Optional[str] = None,
+    key_path: Optional[Path] = None,
+    key_id: str = "local",
+) -> Path:
+    """Assemble a PCRB from a .research workspace. Returns the bundle path."""
+    from skills.research_cache.hasher import SourceHasher
+
+    base_dir = Path(os.path.realpath(str(base_dir)))
+    hasher = SourceHasher(base_dir)
+    synthesis = _resolve_synthesis(base_dir)
+
+    scratch = base_dir / "scratchpads"
+    if scope_ids:
+        scope_dirs = [scratch / s for s in scope_ids]
+    elif scratch.exists():
+        scope_dirs = sorted(p for p in scratch.iterdir() if p.is_dir())
+    else:
+        scope_dirs = []
+
+    claim_records, needed_hashes = _collect_claims(scope_dirs, hasher)
 
     # --- bundled sources (self-contained: full text in the bundle) ---
     sources: Dict[str, Dict[str, Any]] = {}
@@ -162,13 +189,12 @@ def export_brief(
         "sources": {h: sha256_text(s["content"]) for h, s in sources.items()},
     }
 
-    signature = sign_manifest(manifest, _resolve_key(key, key_path), key_id=key_id)
+    resolved_key = _resolve_key(key, key_path)
+    signature = sign_manifest(manifest, resolved_key, key_id=key_id)
 
     bundle = {
         "pcrb_version": PCRB_VERSION,
-        "objective": objective
-        or (json.loads((base_dir / "manifest.json").read_text()).get("objective")
-            if (base_dir / "manifest.json").exists() else None),
+        "objective": _resolve_objective(base_dir, objective),
         "exported_at": datetime.now(timezone.utc).isoformat(),
         "synthesis_markdown": synthesis,
         "claims": claim_records,
@@ -177,7 +203,7 @@ def export_brief(
         "signature": signature,
     }
 
-    out = Path(out_path) if out_path else (base_dir / "brief.pcrb.json")
+    out = Path(os.path.realpath(str(out_path))) if out_path else (base_dir / "brief.pcrb.json")
     out.parent.mkdir(parents=True, exist_ok=True)
     with open(out, "w", encoding="utf-8") as f:
         json.dump(bundle, f, indent=2)
@@ -196,12 +222,15 @@ def main(argv: Optional[List[str]] = None) -> int:
     parser.add_argument("--key-id", default="local")
     args = parser.parse_args(argv)
 
+    canonical_dir = Path(os.path.realpath(str(args.dir)))
+    canonical_out = Path(os.path.realpath(str(args.out))) if args.out else None
+    canonical_key = Path(os.path.realpath(str(args.key_file))) if args.key_file else None
     path = export_brief(
-        Path(args.dir),
-        out_path=Path(args.out) if args.out else None,
+        canonical_dir,
+        out_path=canonical_out,
         scope_ids=args.scope_ids,
         objective=args.objective,
-        key_path=Path(args.key_file) if args.key_file else None,
+        key_path=canonical_key,
         key_id=args.key_id,
     )
     print(json.dumps({"status": "exported", "path": str(path)}))

package/runner/pcrb_verify.py

@@ -25,6 +25,7 @@ import argparse
 import hashlib
 import hmac
 import json
+import os
 import sys
 import tempfile
 import time
@@ -45,21 +46,8 @@ from runner.pcrb import (  # noqa: E402
 )
 
 
-def verify_brief(
-    bundle: Dict[str, Any],
-    key: Optional[bytes] = None,
-) -> Dict[str, Any]:
-    """Run all checks. Returns a structured report dict."""
-    import os
-    started = time.perf_counter()
-    failures: List[Dict[str, str]] = []
-
-    manifest = bundle.get("manifest") or {}
-    signature = bundle.get("signature") or {}
-    claims = bundle.get("claims") or []
-    sources = bundle.get("sources") or {}
-
-    # --- 1. source identity ---
+def _check_source_identity(sources: Dict[str, Any]) -> List[Dict[str, str]]:
+    failures = []
     for src_hash, meta in sources.items():
         content = meta.get("content") or ""
         actual = sha256_text(content)
@@ -69,8 +57,16 @@ def verify_brief(
                 "member": src_hash,
                 "message": f"bundled source content hashes to {actual}, not its key {src_hash}",
             })
+    return failures
+
 
-    # --- 2. manifest integrity ---
+def _check_manifest_integrity(
+    bundle: Dict[str, Any],
+    manifest: Dict[str, Any],
+    claims: List[Dict[str, Any]],
+    sources: Dict[str, Any],
+) -> List[Dict[str, str]]:
+    failures = []
     synth_hash = sha256_text(bundle.get("synthesis_markdown") or "")
     if manifest.get("synthesis_markdown") != synth_hash:
         failures.append({
@@ -79,9 +75,10 @@ def verify_brief(
             "message": "synthesis_markdown does not match its manifest hash",
         })
 
+    manifest_claims = manifest.get("claims") or {}
     for rec in claims:
         cid = rec.get("claim_id", "UNKNOWN")
-        expected = (manifest.get("claims") or {}).get(cid)
+        expected = manifest_claims.get(cid)
         actual = member_hash(rec)
         if expected is None:
             failures.append({"check": "manifest_integrity", "member": cid, "message": "claim missing from manifest"})
@@ -92,8 +89,9 @@ def verify_brief(
                 "message": f"claim hash mismatch (manifest {expected[:16]}… vs actual {actual[:16]}…)",
             })
 
+    manifest_sources = manifest.get("sources") or {}
     for src_hash, meta in sources.items():
-        expected = (manifest.get("sources") or {}).get(src_hash)
+        expected = manifest_sources.get(src_hash)
         actual = sha256_text(meta.get("content") or "")
         if expected is None:
             failures.append({"check": "manifest_integrity", "member": src_hash, "message": "source missing from manifest"})
@@ -103,42 +101,49 @@ def verify_brief(
                 "member": src_hash,
                 "message": "source content does not match its manifest hash",
             })
+    return failures
+
 
-    # --- 3. signature ---
+def _check_signature(
+    signature: Dict[str, Any],
+    manifest: Dict[str, Any],
+    key: Optional[bytes],
+) -> Tuple[str, List[Dict[str, str]]]:
     alg = signature.get("alg") or "none"
-    sig_status = "unsigned"
-    if alg == "hmac-sha256":
-        if not key:
-            sig_status = "unverifiable"
-            failures.append({
-                "check": "signature",
-                "member": "manifest",
-                "message": "brief is HMAC-signed but no key was provided (env IUMBTEMS_PCRB_KEY or --key-file)",
-            })
-        else:
-            expected_sig = hmac.new(key, canonical_json(manifest).encode("utf-8"), hashlib.sha256).hexdigest()
-            provided = signature.get("sig") or ""
-            if not hmac.compare_digest(expected_sig, provided):
-                sig_status = "invalid"
-                failures.append({
-                    "check": "signature",
-                    "member": "manifest",
-                    "message": "HMAC signature does not match manifest (manifest was rewritten or key differs)",
-                })
-            else:
-                sig_status = "valid"
-    # alg == "none": integrity-only mode — coordinated rewrites are NOT
-    # detectable without a key. Reported, not failed.
+    failures = []
+    if alg != "hmac-sha256":
+        return "unsigned", failures
+    if not key:
+        failures.append({
+            "check": "signature",
+            "member": "manifest",
+            "message": "brief is HMAC-signed but no key was provided (env IUMBTEMS_PCRB_KEY or --key-file)",
+        })
+        return "unverifiable", failures
+
+    expected_sig = hmac.new(key, canonical_json(manifest).encode("utf-8"), hashlib.sha256).hexdigest()
+    provided = signature.get("sig") or ""
+    if not hmac.compare_digest(expected_sig, provided):
+        failures.append({
+            "check": "signature",
+            "member": "manifest",
+            "message": "HMAC signature does not match manifest (manifest was rewritten or key differs)",
+        })
+        return "invalid", failures
+    return "valid", failures
+
 
-    # --- 4. quotes against BUNDLED sources (single verification stack) ---
+def _check_quotes(
+    claims: List[Dict[str, Any]],
+    sources: Dict[str, Any],
+) -> Tuple[int, int, List[Dict[str, str]]]:
     quotes_verified = 0
     quotes_failed = 0
+    failures = []
     with tempfile.TemporaryDirectory(prefix="pcrb_verify_") as tmp:
         from skills.research_cache.hasher import SourceHasher
 
         hasher = SourceHasher(Path(tmp))
-        # Materialize bundled sources into the throwaway cache under their
-        # claimed hashes so verify_quote runs its exact/normalized/fuzzy ladder.
         for src_hash, meta in sources.items():
             content = meta.get("content") or ""
             md_path = Path(tmp) / "sources" / f"{src_hash}.md"
@@ -151,7 +156,7 @@ def verify_brief(
             src_hash = witness.get("source_hash") or rec.get("source_hash")
             quote = witness.get("quote") or rec.get("verbatim_quote")
             if not src_hash or not quote:
-                continue  # structural rules live in refinement.check_invariants
+                continue
             if src_hash not in sources:
                 quotes_failed += 1
                 failures.append({
@@ -170,6 +175,27 @@ def verify_brief(
                     "member": cid,
                     "message": f"quote not found in bundled source (conf={conf}): {msg}",
                 })
+    return quotes_verified, quotes_failed, failures
+
+
+def verify_brief(
+    bundle: Dict[str, Any],
+    key: Optional[bytes] = None,
+) -> Dict[str, Any]:
+    """Run all checks. Returns a structured report dict."""
+    started = time.perf_counter()
+    manifest = bundle.get("manifest") or {}
+    signature = bundle.get("signature") or {}
+    claims = bundle.get("claims") or []
+    sources = bundle.get("sources") or {}
+
+    failures: List[Dict[str, str]] = []
+    failures.extend(_check_source_identity(sources))
+    failures.extend(_check_manifest_integrity(bundle, manifest, claims, sources))
+    sig_status, sig_failures = _check_signature(signature, manifest, key)
+    failures.extend(sig_failures)
+    quotes_verified, quotes_failed, quote_failures = _check_quotes(claims, sources)
+    failures.extend(quote_failures)
 
     elapsed = time.perf_counter() - started
     return {
@@ -198,8 +224,8 @@ def main(argv: Optional[List[str]] = None) -> int:
     parser.add_argument("--key-file", default=None)
     args = parser.parse_args(argv)
 
-    path = Path(args.brief)
-    if not path.exists():
+    path = Path(os.path.realpath(str(args.brief)))
+    if not path.is_file():
         print(f"error: no such brief: {path}", file=sys.stderr)
         return 2
     try:
@@ -208,11 +234,15 @@ def main(argv: Optional[List[str]] = None) -> int:
         print(f"error: unreadable brief: {exc}", file=sys.stderr)
         return 2
 
-    import os
-
     key = None
-    if args.key_file and Path(args.key_file).exists():
-        key = Path(args.key_file).read_bytes().strip()
+    if args.key_file:
+        key_file_path = Path(os.path.realpath(str(args.key_file)))
+        # Fail loudly rather than fall through to an unsigned verification:
+        # a typo'd --key-file would otherwise silently verify with no key.
+        if not key_file_path.is_file():
+            print(f"error: key file is not a readable file: {args.key_file}", file=sys.stderr)
+            return 2
+        key = key_file_path.read_bytes().strip()
     elif os.environ.get(ENV_KEY):
         key = os.environ[ENV_KEY].encode("utf-8")