wardn 0.1.0.dev0__py3-none-any.whl

wardn/ledger.py

@@ -0,0 +1,237 @@
+"""The ledger: append-only JSON Lines, timestamp-free, byte-deterministic.
+
+One header line, then a closed set of five event kinds:
+
+  attempt   — a tool call reached the gate; written BEFORE forwarding, so a
+              crash mid-call leaves "committed, no result recorded" instead
+              of silence. Carries the full decision.
+  approval  — the human verdict for a quarantined attempt (an INPUT: replay
+              feeds it back in; it is not recomputed).
+  capture   — the pre-state wardn read before forwarding, plus the resolved
+              undo call and revert-time check. Revert needs the file alone.
+  result    — what the server returned for a forwarded call.
+  tools     — the annotation snapshot from a tools/list response passing
+              through (what the server CLAIMED; classification input).
+
+Determinism: no timestamps, no PIDs, no nonces. `run_id` is a workload
+label — identical across runs you intend to compare; uniqueness lives in
+the file name. Two identical runs (same policy, same requests, same
+approvals, same server behavior) emit byte-identical files.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ._version import __version__
+from .engine import Engine
+from .policy import Policy
+from .types import Decision, ToolAnnotations, ToolRequest, WardnError
+
+LEDGER_FORMAT = "wardn-ledger/1"
+
+EVENT_KINDS = ("attempt", "approval", "capture", "result", "tools")
+
+
+class LedgerError(WardnError):
+    pass
+
+
+class ReplayDivergence(WardnError):
+    pass
+
+
+def _line(obj: dict) -> bytes:
+    return (json.dumps(obj, separators=(",", ":"), ensure_ascii=True) + "\n") \
+        .encode("utf-8")
+
+
+class LedgerWriter:
+    """Appends one event per line, flushed per event (crash honesty)."""
+
+    def __init__(self, path, run_id: str, policy: Policy, servers: list):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        header = {
+            "format": LEDGER_FORMAT,
+            "run_id": run_id,
+            "provenance": {
+                "wardn_version": __version__,
+                "servers": list(servers),
+                "policy": policy.provenance_lines(),
+                "policy_hash": policy.hash(),
+            },
+        }
+        self._fh = self.path.open("wb")
+        self._emit(header)
+
+    def _emit(self, obj: dict) -> None:
+        self._fh.write(_line(obj))
+        self._fh.flush()
+
+    def attempt(self, seq: int, req: ToolRequest, decision: Decision) -> None:
+        self._emit({"kind": "attempt", "seq": seq, "server": req.server,
+                    "tool": req.tool, "args": req.args,
+                    "matched_rule": decision.matched_rule,
+                    "effect": decision.effect,
+                    "effect_source": decision.effect_source,
+                    "disposition": decision.disposition,
+                    "reason": decision.reason, "cost": decision.cost,
+                    "refusal": decision.refusal})
+
+    def approval(self, seq: int, verdict: str, by: str) -> None:
+        self._emit({"kind": "approval", "seq": seq, "verdict": verdict,
+                    "by": by})
+
+    def capture(self, seq: int, tool: str, args: dict, state: dict,
+                undo: dict | None, check: dict | None) -> None:
+        self._emit({"kind": "capture", "seq": seq, "tool": tool, "args": args,
+                    "state": state, "undo": undo, "check": check})
+
+    def result(self, seq: int, is_error: bool, content: list) -> None:
+        self._emit({"kind": "result", "seq": seq, "is_error": is_error,
+                    "content": content})
+
+    def tools(self, server: str, hints: dict) -> None:
+        """hints: tool name -> {"readOnlyHint": ..., "destructiveHint": ...}"""
+        self._emit({"kind": "tools", "server": server,
+                    "tools": {name: hints[name] for name in sorted(hints)}})
+
+    def close(self) -> None:
+        self._fh.close()
+
+
+# ---------------------------------------------------------------------------
+# Reading
+# ---------------------------------------------------------------------------
+
+def read_ledger(path) -> tuple:
+    """(header, events). Refuses any format other than wardn-ledger/1."""
+    if not Path(path).exists():
+        raise LedgerError(f"{path}: no such file")
+    lines = Path(path).read_text(encoding="utf-8").splitlines()
+    if not lines:
+        raise LedgerError(f"{path}: empty file")
+    header = json.loads(lines[0])
+    if header.get("format") != LEDGER_FORMAT:
+        raise LedgerError(
+            f"{path}: format {header.get('format')!r} is not {LEDGER_FORMAT!r}")
+    events = [json.loads(line) for line in lines[1:]]
+    for event in events:
+        if event.get("kind") not in EVENT_KINDS:
+            raise LedgerError(f"{path}: unknown event kind {event.get('kind')!r}")
+    return header, events
+
+
+class Folded:
+    """One attempt with its approval / capture / result gathered up."""
+
+    def __init__(self, attempt: dict):
+        self.attempt = attempt
+        self.approval: dict | None = None
+        self.capture: dict | None = None
+        self.result: dict | None = None
+
+    @property
+    def seq(self) -> int:
+        return self.attempt["seq"]
+
+    @property
+    def committed(self) -> bool:
+        """Was this call committed for forwarding? (It may still have no
+        result — a crash between commit and response is exactly the case
+        the event split exists for.)"""
+        if self.attempt["refusal"]:
+            return False
+        if self.attempt["disposition"] == "quarantine":
+            return self.approval is not None \
+                and self.approval["verdict"] == "approve"
+        return True
+
+    @property
+    def executed(self) -> bool:
+        """Committed, forwarded, and the server reported success."""
+        return self.committed and self.result is not None \
+            and not self.result["is_error"]
+
+
+def fold(events: list) -> list:
+    """Events -> Folded attempts, in seq order."""
+    by_seq: dict = {}
+    for event in events:
+        kind = event["kind"]
+        if kind == "tools":
+            continue
+        if kind == "attempt":
+            by_seq[event["seq"]] = Folded(event)
+        else:
+            folded = by_seq.get(event["seq"])
+            if folded is None:
+                raise LedgerError(
+                    f"{kind} event for seq {event['seq']} without an attempt")
+            setattr(folded, kind, event)
+    return [by_seq[seq] for seq in sorted(by_seq)]
+
+
+# ---------------------------------------------------------------------------
+# Offline replay: policy + file -> the same decisions. No server, no queue.
+# ---------------------------------------------------------------------------
+
+def replay(policy: Policy, path) -> int:
+    """Re-derives every decision and compares it with what the ledger
+    recorded. Approvals and annotation snapshots are read back as inputs.
+    Returns the number of attempts replayed; raises ReplayDivergence on the
+    first mismatch."""
+    header, events = read_ledger(path)
+    recorded_hash = header["provenance"]["policy_hash"]
+    if recorded_hash != policy.hash():
+        raise ReplayDivergence(
+            f"policy hash mismatch: ledger has {recorded_hash}, "
+            f"this policy is {policy.hash()} — not the policy that ran")
+
+    engine = Engine(policy)
+    annotations: dict = {}   # server name -> {tool name -> ToolAnnotations}
+    pending: dict = {}   # seq -> Decision awaiting its approval event
+    attempts = 0
+
+    for event in events:
+        kind = event["kind"]
+        if kind == "tools":
+            # wholesale replacement per server, mirroring the proxy: a
+            # fresh snapshot forgets tools the server no longer lists
+            annotations[event["server"]] = {
+                name: ToolAnnotations(read_only=h.get("readOnlyHint"),
+                                      destructive=h.get("destructiveHint"))
+                for name, h in event["tools"].items()}
+        elif kind == "attempt":
+            req = ToolRequest(server=event["server"], tool=event["tool"],
+                              args=event["args"])
+            decision = engine.decide(
+                req, annotations.get(req.server, {}).get(req.tool))
+            recorded = tuple(event[f] for f in
+                             ("matched_rule", "effect", "effect_source",
+                              "disposition", "reason", "cost", "refusal"))
+            derived = (decision.matched_rule, decision.effect,
+                       decision.effect_source, decision.disposition,
+                       decision.reason, decision.cost, decision.refusal)
+            if recorded != derived:
+                raise ReplayDivergence(
+                    f"seq {event['seq']}: ledger says {recorded}, "
+                    f"policy derives {derived}")
+            attempts += 1
+            if not decision.refusal:
+                if decision.disposition == "quarantine":
+                    pending[event["seq"]] = decision
+                else:
+                    engine.note_forwarded(decision)
+        elif kind == "approval":
+            decision = pending.pop(event["seq"], None)
+            if decision is None:
+                raise ReplayDivergence(
+                    f"seq {event['seq']}: approval without pending quarantine")
+            if event["verdict"] == "approve":
+                engine.note_forwarded(decision)
+        # capture / result events carry no decision to re-derive
+
+    return attempts

wardn/matchers.py

@@ -0,0 +1,62 @@
+"""Matching: server exact, tool glob, argument constraints on dotted paths.
+
+Argument constraints are STRING and NUMBER constraints, not path resolution:
+`path_prefix: "out/"` happily matches `"out/../secret.txt"`. wardn does not
+normalize `..` or resolve symlinks — that is a sandbox's job, and wardn is
+not a sandbox.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+
+from .policy import Match
+
+_MISSING = object()
+
+
+def lookup(args: dict, dotted: str):
+    current = args
+    for part in dotted.split("."):
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return _MISSING
+    return current
+
+
+def arg_matches(constraint: dict, value) -> bool:
+    for op, want in constraint.items():
+        if op == "equals":
+            if value != want:
+                return False
+        elif op == "glob":
+            if not (isinstance(value, str)
+                    and fnmatch.fnmatchcase(value, want)):
+                return False
+        elif op == "path_prefix":
+            if not (isinstance(value, str) and value.startswith(want)):
+                return False
+        elif op == "lte":
+            if not (isinstance(value, (int, float))
+                    and not isinstance(value, bool) and value <= want):
+                return False
+        elif op == "gte":
+            if not (isinstance(value, (int, float))
+                    and not isinstance(value, bool) and value >= want):
+                return False
+        else:  # unreachable after strict policy loading; loud anyway
+            raise ValueError(f"unknown arg operator: {op}")
+    return True
+
+
+def match_matches(match: Match, server: str, tool: str, args: dict) -> bool:
+    if match.server is not None and match.server != server:
+        return False
+    if match.tool is not None and not fnmatch.fnmatchcase(tool, match.tool):
+        return False
+    for path, constraint in match.args.items():
+        value = lookup(args, path)
+        if value is _MISSING or not arg_matches(constraint, value):
+            return False
+    return True

wardn/orchestrator.py

@@ -0,0 +1,122 @@
+"""Governing one tool call, independent of transport.
+
+`govern_call` is the whole loop for a single attempt: decide → (approval) →
+(capture) → forward → record. The MCP proxy wires it to JSON-RPC pipes;
+tests wire it to an in-process fake. Both get identical semantics because
+this is the only implementation of them.
+
+The `caller` contract: caller(tool, args) -> {"content": [...], "isError": bool}
+— an MCP-shaped tool result. The `approver` contract:
+approver(seq, req, decision) -> (verdict, by) with verdict in
+("approve", "deny", "timeout").
+"""
+
+from __future__ import annotations
+
+from .engine import Engine
+from .ledger import LedgerWriter
+from .policy import Rule
+from .types import Decision, ToolAnnotations, ToolRequest
+
+_UNRESOLVED = object()
+
+
+def refusal_result(message: str) -> dict:
+    """The loud refusal the client sees: an MCP tool error naming the rule
+    and bound, so the agent can read why and adapt."""
+    return {"content": [{"type": "text", "text": f"wardn refused: {message}"}],
+            "isError": True}
+
+
+def text_of(content: list) -> str:
+    return "".join(part.get("text", "") for part in content
+                   if isinstance(part, dict) and part.get("type") == "text")
+
+
+def _resolve(template, args: dict, capture_value):
+    if isinstance(template, str) and template.startswith("$"):
+        if template == "$capture.value":
+            return capture_value if capture_value is not None else _UNRESOLVED
+        if template.startswith("$args."):
+            return args.get(template[len("$args."):], _UNRESOLVED)
+    return template
+
+
+def _resolve_args(templates: dict, args: dict, capture_value) -> dict | None:
+    resolved = {}
+    for key, template in templates.items():
+        value = _resolve(template, args, capture_value)
+        if value is _UNRESOLVED:
+            return None
+        resolved[key] = value
+    return resolved
+
+
+def _build_capture(rule: Rule, req: ToolRequest, caller):
+    """Take the declared pre-state read and resolve the undo NOW, so the
+    ledger file alone suffices to revert — no policy needed at revert time."""
+    capture = rule.capture
+    if any(source not in req.args for source in capture.args_from.values()):
+        # The request lacks an arg the capture needs: no pre-state, no undo.
+        # Recorded as irreversible rather than guessed at.
+        return {}, {"unresolved": True}, None, None
+    cap_args = {to: req.args[source]
+                for to, source in capture.args_from.items()}
+    read = caller(capture.tool, cap_args)
+    if read.get("isError"):
+        state = {"exists": False}
+        value = None
+    else:
+        value = text_of(read.get("content", []))
+        state = {"exists": True, "value": value}
+
+    undo = None
+    check = None
+    inverse = rule.inverse
+    if inverse is not None:
+        if state["exists"]:
+            undo_args = _resolve_args(inverse.args, req.args, value)
+            if undo_args is not None:
+                undo = {"tool": inverse.tool, "args": undo_args}
+        elif inverse.when_absent_tool is not None:
+            undo_args = _resolve_args(inverse.when_absent_args or {},
+                                      req.args, None)
+            if undo_args is not None:
+                undo = {"tool": inverse.when_absent_tool, "args": undo_args}
+        if inverse.expect == "$absent":
+            check = {"expect_absent": True}
+        elif inverse.expect is not None:
+            expected = _resolve(inverse.expect, req.args, value)
+            if expected is not _UNRESOLVED:
+                check = {"expect": expected}
+    return cap_args, state, undo, check
+
+
+def govern_call(engine: Engine, writer: LedgerWriter, seq: int,
+                req: ToolRequest, ann: ToolAnnotations | None,
+                caller, approver) -> dict:
+    """Returns the MCP-shaped result to hand back to the client — the
+    server's own result when forwarded, a refusal result otherwise. Every
+    path lands in the ledger."""
+    decision = engine.decide(req, ann)
+    writer.attempt(seq, req, decision)
+
+    if decision.refusal:
+        return refusal_result(decision.refusal)
+
+    if decision.disposition == "quarantine":
+        verdict, by = approver(seq, req, decision)
+        writer.approval(seq, verdict, by)
+        if verdict != "approve":
+            return refusal_result(
+                f"quarantine verdict {verdict} (rule {decision.matched_rule})")
+
+    rule = engine.policy.rule_by_id(decision.matched_rule)
+    if rule is not None and rule.capture is not None:
+        cap_args, state, undo, check = _build_capture(rule, req, caller)
+        writer.capture(seq, rule.capture.tool, cap_args, state, undo, check)
+
+    engine.note_forwarded(decision)
+    result = caller(req.tool, req.args)
+    writer.result(seq, bool(result.get("isError")), result.get("content", []))
+    return result