@heretek-ai/epistemic-swarm 0.4.6 → 0.4.8

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")
 

package/runner/refinement.py

@@ -18,6 +18,7 @@ V(c_i) has never been what the runtime computes. Tier weighting becomes an
 opt-in constitution — nothing flips without an explicit pack.
 """
 
+import math
 from dataclasses import dataclass, field
 from typing import Any, Dict, Iterable, List, Optional, Tuple
 
@@ -154,6 +155,59 @@ def claim_verdict(
     }
 
 
+def _check_verified_and_inferred(c: ClaimWitness, hasher: Any, out: List[Violation]) -> None:
+    if c.tag == TAG_VERIFIED or c.kind == KIND_CLAIM:
+        if not c.source_hash:
+            out.append(Violation(c.claim_id, "VERIFIED_REQUIRES_HASH", "source_hash missing"))
+        if not c.verbatim_quote:
+            out.append(Violation(c.claim_id, "VERIFIED_REQUIRES_QUOTE", "verbatim_quote missing"))
+        if hasher is not None and c.source_hash and c.verbatim_quote:
+            passed, _conf, msg = witness_check(c, hasher)
+            if not passed:
+                out.append(Violation(c.claim_id, "WITNESS_CHECK_FAILED", msg or "quote not in source"))
+
+    if c.tag == TAG_INFERRED or c.kind == KIND_INFERENCE:
+        if not c.parent_claims:
+            out.append(Violation(c.claim_id, "INFERRED_REQUIRES_PARENTS", "parent_claims empty"))
+        if not c.deductive_logic:
+            out.append(Violation(c.claim_id, "INFERRED_REQUIRES_LOGIC", "deductive_logic missing"))
+
+
+def _check_hypotheses_and_neg_knowledge(c: ClaimWitness, out: List[Violation]) -> None:
+    if (c.tag == TAG_HYPOTHESIS or c.kind == KIND_HYPOTHESIS) and not c.falsification:
+        out.append(Violation(c.claim_id, "HYPOTHESIS_REQUIRES_FALSIFICATION", "falsification missing"))
+
+    if c.tag == TAG_NEGATIVE_KNOWLEDGE or c.kind == KIND_NEGATIVE_KNOWLEDGE:
+        if not c.query:
+            out.append(Violation(c.claim_id, "NEG_KNOWLEDGE_REQUIRES_QUERY", "query missing"))
+        if not c.finding:
+            out.append(Violation(c.claim_id, "NEG_KNOWLEDGE_REQUIRES_FINDING", "finding missing"))
+
+
+def _check_constitution_and_parents(
+    c: ClaimWitness,
+    known_ids: set,
+    constitution: Constitution,
+    out: List[Violation],
+) -> None:
+    for parent in c.parent_claims:
+        if parent not in known_ids:
+            out.append(
+                Violation(c.claim_id, "PARENT_UNRESOLVED", f"parent_claims '{parent}' not in dossier set")
+            )
+
+    if constitution.mandatory_tags and not c.tag:
+        out.append(Violation(c.claim_id, "MISSING_TAG", "tag required by constitution"))
+
+    if constitution.banned_domains and c.source_url:
+        src_lower = c.source_url.lower()
+        for dom in constitution.banned_domains:
+            if dom.lower() in src_lower:
+                out.append(
+                    Violation(c.claim_id, "BANNED_DOMAIN", f"source_url on banned domain '{dom}'")
+                )
+
+
 def check_invariants(
     claims: Iterable[ClaimWitness],
     hasher: Any = None,
@@ -165,54 +219,14 @@ def check_invariants(
     VERIFIED claims; without it, only structural rules are enforced.
     """
     constitution = constitution or LEGACY_CONSTITUTION
-    claims = list(claims)
-    known_ids = {c.claim_id for c in claims}
+    claim_list = list(claims)
+    known_ids = {c.claim_id for c in claim_list}
     out: List[Violation] = []
 
-    for c in claims:
-        # --- tag/kind-specific structural rules ---
-        if c.tag == TAG_VERIFIED or c.kind == KIND_CLAIM:
-            if not c.source_hash:
-                out.append(Violation(c.claim_id, "VERIFIED_REQUIRES_HASH", "source_hash missing"))
-            if not c.verbatim_quote:
-                out.append(Violation(c.claim_id, "VERIFIED_REQUIRES_QUOTE", "verbatim_quote missing"))
-            if hasher is not None and c.source_hash and c.verbatim_quote:
-                passed, _conf, msg = witness_check(c, hasher)
-                if not passed:
-                    out.append(Violation(c.claim_id, "WITNESS_CHECK_FAILED", msg or "quote not in source"))
-
-        if c.tag == TAG_INFERRED or c.kind == KIND_INFERENCE:
-            if not c.parent_claims:
-                out.append(Violation(c.claim_id, "INFERRED_REQUIRES_PARENTS", "parent_claims empty"))
-            if not c.deductive_logic:
-                out.append(Violation(c.claim_id, "INFERRED_REQUIRES_LOGIC", "deductive_logic missing"))
-
-        if c.tag == TAG_HYPOTHESIS or c.kind == KIND_HYPOTHESIS:
-            if not c.falsification:
-                out.append(Violation(c.claim_id, "HYPOTHESIS_REQUIRES_FALSIFICATION", "falsification missing"))
-
-        if c.tag == TAG_NEGATIVE_KNOWLEDGE or c.kind == KIND_NEGATIVE_KNOWLEDGE:
-            if not c.query:
-                out.append(Violation(c.claim_id, "NEG_KNOWLEDGE_REQUIRES_QUERY", "query missing"))
-            if not c.finding:
-                out.append(Violation(c.claim_id, "NEG_KNOWLEDGE_REQUIRES_FINDING", "finding missing"))
-
-        # --- cross-reference resolution ---
-        for parent in c.parent_claims:
-            if parent not in known_ids:
-                out.append(
-                    Violation(c.claim_id, "PARENT_UNRESOLVED", f"parent_claims '{parent}' not in dossier set")
-                )
-
-        # --- domain-pack rules ---
-        if constitution.mandatory_tags and not c.tag:
-            out.append(Violation(c.claim_id, "MISSING_TAG", "tag required by constitution"))
-        if constitution.banned_domains and c.source_url:
-            for dom in constitution.banned_domains:
-                if dom.lower() in c.source_url.lower():
-                    out.append(
-                        Violation(c.claim_id, "BANNED_DOMAIN", f"source_url on banned domain '{dom}'")
-                    )
+    for c in claim_list:
+        _check_verified_and_inferred(c, hasher, out)
+        _check_hypotheses_and_neg_knowledge(c, out)
+        _check_constitution_and_parents(c, known_ids, constitution, out)
 
     return out
 
@@ -294,7 +308,7 @@ def compute_epistemic_score_from_claims(
     }
     weight_sum = 0.0
     tier_weighted = any(
-        w != 1.0 for w in constitution.tier_weights.values()
+        not math.isclose(w, 1.0, rel_tol=1e-7) for w in constitution.tier_weights.values()
     )
 
     for c in claims: