delego 0.2.0__py3-none-any.whl

delego/__init__.py

@@ -0,0 +1,48 @@
+"""delego — a policy & audit firewall for agent actions.
+
+This package authorises an *action* (deterministically, no LLM in the loop)
+before any credential is used, parks sensitive actions for human approval, and
+writes a tamper-evident signed audit chain. See ``ARCHITECTURE.md`` for the design
+invariants and ``examples/demo.py`` for the de facto spec.
+
+The names below are the public API: the CLI (``delego.cli``) and MCP server
+(``delego.mcp_server``) are entry points, everything else an integrator needs is
+re-exported here. This module is re-export only — no logic lives here.
+"""
+
+from __future__ import annotations
+
+from .audit import AuditLog, ensure_keys
+from .config import Paths, build_firewall
+from .engine import Firewall
+from .models import (
+    OUTCOME_ALLOW,
+    OUTCOME_APPROVAL,
+    OUTCOME_DENY,
+    Decision,
+    ProposedAction,
+)
+from .policy import Policy
+
+__version__ = "0.2.0"  # package (PyPI) version
+
+# Highest delego *protocol* version (see the wire spec's "Protocol versions")
+# this reference implements. The spec leads the reference: the spec's version
+# MUST always be >= this. Distinct from __version__, the package release version.
+__protocol_version__ = "0.2.0"
+
+__all__ = [
+    "ProposedAction",
+    "Decision",
+    "Firewall",
+    "Policy",
+    "AuditLog",
+    "ensure_keys",
+    "Paths",
+    "build_firewall",
+    "OUTCOME_ALLOW",
+    "OUTCOME_DENY",
+    "OUTCOME_APPROVAL",
+    "__version__",
+    "__protocol_version__",
+]

delego/approval.py

@@ -0,0 +1,108 @@
+"""Human-in-the-loop approval queue.
+
+When the policy says ``needs_approval``, the firewall parks the action here and
+a human decides out-of-band (via the CLI: ``delego approve <id>``). Each record
+is bound to the action's fingerprint, so an approval can only ever release the
+*exact* action it was granted for.
+
+v0.1 storage is an append-only JSONL file (last record per id wins). It's
+deliberately simple and inspectable; a real deployment would put this behind
+the daemon with proper access control.
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+from pathlib import Path
+from typing import Optional
+
+from .util import now_iso
+
+STATUS_PENDING = "pending"
+STATUS_APPROVED = "approved"
+STATUS_DENIED = "denied"
+STATUS_CONSUMED = "consumed"  # approved AND already released — single-use, never again
+
+
+class ApprovalStore:
+    def __init__(self, path):
+        self.path = Path(path)
+
+    def _read(self) -> dict[str, dict]:
+        records: dict[str, dict] = {}
+        if not self.path.exists():
+            return records
+        for line in self.path.read_text(encoding="utf-8").splitlines():
+            if line.strip():
+                rec = json.loads(line)
+                records[rec["id"]] = rec  # later (decided) records overwrite earlier ones
+        return records
+
+    def _append(self, rec: dict) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(rec) + "\n")
+
+    def create(
+        self,
+        *,
+        action_fingerprint: str,
+        intent_hash: str,
+        summary: str,
+        instruction: str = "",
+        rule: Optional[str] = None,
+    ) -> str:
+        approval_id = "apr_" + secrets.token_hex(6)
+        self._append(
+            {
+                "id": approval_id,
+                "status": STATUS_PENDING,
+                "action_fingerprint": action_fingerprint,
+                "intent_hash": intent_hash,
+                # The human-readable instruction (so the approver sees *what* they
+                # are authorising, not just its hash) and the rule that parked it
+                # (so the execution receipt can attribute the allow correctly).
+                "instruction": instruction,
+                "rule": rule,
+                "summary": summary,
+                "created_at": now_iso(),
+                "decided_at": None,
+                "approver": None,
+            }
+        )
+        return approval_id
+
+    def get(self, approval_id: str) -> Optional[dict]:
+        return self._read().get(approval_id)
+
+    def decide(self, approval_id: str, approved: bool, approver: str = "cli") -> Optional[dict]:
+        rec = self.get(approval_id)
+        if rec is None:
+            return None
+        if rec["status"] != STATUS_PENDING:
+            return rec  # already decided; idempotent
+        updated = {
+            **rec,
+            "status": STATUS_APPROVED if approved else STATUS_DENIED,
+            "decided_at": now_iso(),
+            "approver": approver,
+        }
+        self._append(updated)
+        return updated
+
+    def consume(self, approval_id: str) -> Optional[dict]:
+        """Mark an approved action as released. Single-use: an approval can only
+        ever execute once, so a replayed ``resolve`` of the same approved id is
+        refused. Transitions ``approved`` -> ``consumed``; a no-op otherwise."""
+        rec = self.get(approval_id)
+        if rec is None:
+            return None
+        if rec["status"] != STATUS_APPROVED:
+            return rec  # only an approved action can be consumed
+        updated = {**rec, "status": STATUS_CONSUMED, "consumed_at": now_iso()}
+        self._append(updated)
+        return updated
+
+    def pending(self) -> list[dict]:
+        return [r for r in self._read().values() if r["status"] == STATUS_PENDING]

delego/audit.py

@@ -0,0 +1,211 @@
+"""Tamper-evident audit log.
+
+Every decision the firewall makes is written as a *receipt*. Receipts form a
+hash chain (each carries the previous receipt's hash) and each is signed with a
+local Ed25519 key. That gives two properties a regulator actually asks for:
+
+* **Integrity** — editing or deleting any past receipt breaks the chain, and
+  re-signing requires the private key.
+* **Reconstructable authority path** — every receipt records the intent hash,
+  the action fingerprint, the matched rule, and the outcome, so you can replay
+  exactly *why* an action was allowed and *which instruction* authorised it.
+
+This is the append-only ledger; ``verify()`` walks and checks the whole chain.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from .util import canonical_json, now_iso, sha256_hex
+
+# Fields that make up the signed payload, in a fixed set. ``entry_hash`` and
+# ``signature`` are derived from these and excluded from the hashed payload.
+_PAYLOAD_KEYS = (
+    "seq",
+    "ts",
+    "phase",
+    "outcome",
+    "rule",
+    "reasons",
+    "intent_hash",
+    "action_fingerprint",
+    "action_summary",
+    "approval_id",
+    "prev_hash",
+)
+
+GENESIS = "GENESIS"
+
+
+def ensure_keys(priv_path: Path, pub_path: Path) -> None:
+    """Generate a local Ed25519 signing keypair if one doesn't exist."""
+    priv_path = Path(priv_path)
+    pub_path = Path(pub_path)
+    if priv_path.exists():
+        return
+    priv_path.parent.mkdir(parents=True, exist_ok=True)
+    priv = Ed25519PrivateKey.generate()
+    priv_path.write_bytes(
+        priv.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+    )
+    os.chmod(priv_path, 0o600)
+    pub_path.write_bytes(
+        priv.public_key().public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+    )
+
+
+class AuditLog:
+    def __init__(self, path, private_key_path, public_key_path):
+        self.path = Path(path)
+        self.priv_path = Path(private_key_path)
+        self.pub_path = Path(public_key_path)
+        self._priv: Optional[Ed25519PrivateKey] = None
+        self._pub: Optional[Ed25519PublicKey] = None
+
+    # -- keys ------------------------------------------------------------- #
+    def _load_keys(self) -> None:
+        if self._priv is None:
+            self._priv = serialization.load_pem_private_key(
+                self.priv_path.read_bytes(), password=None
+            )
+            self._pub = serialization.load_pem_public_key(self.pub_path.read_bytes())
+
+    # -- read --------------------------------------------------------------#
+    def _entries(self) -> list[dict]:
+        if not self.path.exists():
+            return []
+        out = []
+        for line in self.path.read_text(encoding="utf-8").splitlines():
+            if line.strip():
+                out.append(json.loads(line))
+        return out
+
+    def _last(self) -> Optional[dict]:
+        entries = self._entries()
+        return entries[-1] if entries else None
+
+    # -- write ------------------------------------------------------------ #
+    def append(
+        self,
+        *,
+        phase: str,
+        outcome: str,
+        rule: Optional[str],
+        reasons: list[str],
+        intent_hash: str,
+        action_fingerprint: str,
+        action_summary: str,
+        approval_id: Optional[str] = None,
+    ) -> dict:
+        self._load_keys()
+        last = self._last()
+        seq = (last["seq"] + 1) if last else 0
+        prev_hash = last["entry_hash"] if last else GENESIS
+
+        payload = {
+            "seq": seq,
+            "ts": now_iso(),
+            "phase": phase,
+            "outcome": outcome,
+            "rule": rule,
+            "reasons": reasons,
+            "intent_hash": intent_hash,
+            "action_fingerprint": action_fingerprint,
+            "action_summary": action_summary,
+            "approval_id": approval_id,
+            "prev_hash": prev_hash,
+        }
+        entry_hash = sha256_hex(canonical_json(payload))
+        signature = self._priv.sign(entry_hash.encode("utf-8")).hex()
+        entry = {**payload, "entry_hash": entry_hash, "signature": signature}
+
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(entry) + "\n")
+        return entry
+
+    # -- verify ----------------------------------------------------------- #
+    def verify(self) -> tuple[bool, list[str]]:
+        """Walk the chain: recompute hashes, check linkage, verify signatures.
+
+        Tampering takes many forms — an edited field, a *removed* field, an
+        unparseable line — so every step is defensive: a malformed receipt is
+        reported as a problem, never allowed to crash the verification (a verifier
+        that throws is a verifier an attacker can silence by corrupting one line).
+        """
+        self._load_keys()
+        problems: list[str] = []
+        prev = GENESIS
+        if not self.path.exists():
+            return True, []
+        for lineno, line in enumerate(self.path.read_text(encoding="utf-8").splitlines()):
+            if not line.strip():
+                continue
+            try:
+                e = json.loads(line)
+            except Exception:
+                problems.append(f"line {lineno}: unparseable receipt (corrupt)")
+                prev = None  # the chain cannot link across a broken line
+                continue
+            where = f"seq {e['seq']}" if isinstance(e, dict) and "seq" in e else f"line {lineno}"
+            try:
+                payload = {k: e[k] for k in _PAYLOAD_KEYS}
+            except (KeyError, TypeError):
+                missing = [k for k in _PAYLOAD_KEYS if not (isinstance(e, dict) and k in e)]
+                problems.append(f"{where}: missing field(s) {missing} (tampered)")
+                prev = e.get("entry_hash") if isinstance(e, dict) else None
+                continue
+            recomputed = sha256_hex(canonical_json(payload))
+            if recomputed != e.get("entry_hash"):
+                problems.append(f"{where}: content hash mismatch (tampered)")
+            if e.get("prev_hash") != prev:
+                problems.append(f"{where}: broken chain link")
+            try:
+                self._pub.verify(bytes.fromhex(e["signature"]), e["entry_hash"].encode("utf-8"))
+            except Exception:
+                problems.append(f"{where}: bad signature")
+            prev = e.get("entry_hash")
+        return (len(problems) == 0), problems
+
+    # -- queries ---------------------------------------------------------- #
+    def tail(self, n: int = 20) -> list[dict]:
+        return self._entries()[-n:]
+
+    def count_allows(self, rule: str, within_seconds: int) -> int:
+        """How many times ``rule`` has been allowed within the time window.
+
+        Used by the rate-limit constraint. Counts ``allow`` receipts (the moment
+        of authorisation) for the given rule.
+        """
+        from time import time
+
+        cutoff = time() - within_seconds
+        count = 0
+        for e in self._entries():
+            if e.get("rule") != rule or e.get("outcome") != "allow":
+                continue
+            try:
+                ts = datetime.fromisoformat(e["ts"]).timestamp()
+            except Exception:
+                continue
+            if ts >= cutoff:
+                count += 1
+        return count

delego/brokers.py

@@ -0,0 +1,72 @@
+"""Broker adapters: where the *authorised* action actually gets executed.
+
+This firewall does not hold credentials. Once it has authorised an action, it
+hands the action to a broker that injects the user's credential and forwards the
+request upstream. The agent — and this firewall — never see the secret.
+
+That is the existing, crowded layer (Infisical Agent Vault, OneCLI, Browser Use,
+etc.). The point of keeping it behind a thin ``BrokerAdapter`` interface is that
+you ride that layer instead of rebuilding it: swap ``NullBroker`` for a real
+adapter and the decision/audit logic above is unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from .models import ProposedAction
+
+
+@runtime_checkable
+class BrokerAdapter(Protocol):
+    name: str
+
+    def execute(self, action: ProposedAction) -> dict[str, Any]:
+        ...
+
+
+class NullBroker:
+    """Default stand-in broker. Holds NO credentials and makes NO real request.
+
+    It records what *would* have been sent so the full decision -> execution
+    loop is observable end to end. Use it for local development, demos, and
+    tests; replace it with a real adapter for anything that touches a live
+    service.
+    """
+
+    name = "null"
+
+    def __init__(self) -> None:
+        self.sent: list[dict] = []
+
+    def execute(self, action: ProposedAction) -> dict[str, Any]:
+        record = {
+            "broker": self.name,
+            "would_send": action.summary(),
+            "note": "stub: no credential injected, no upstream request made",
+        }
+        self.sent.append(record)
+        return {"status": "simulated", "detail": record}
+
+
+class HTTPProxyBroker:
+    """Sketch of a real adapter — NOT wired up in v0.1.
+
+    In production this points at a running credential broker (for example
+    OneCLI's gateway on ``localhost:10255``, or an Agent Vault proxy). The broker
+    matches a credential by host/path, injects it, and forwards the request. The
+    firewall has already decided the action is allowed; this adapter only carries
+    it through the component that actually holds the secret.
+    """
+
+    name = "http_proxy"
+
+    def __init__(self, proxy_url: str) -> None:
+        self.proxy_url = proxy_url
+
+    def execute(self, action: ProposedAction) -> dict[str, Any]:
+        raise NotImplementedError(
+            "Wire this to your credential broker. Route the request through "
+            f"{self.proxy_url!r}; the broker injects the credential and forwards "
+            "upstream. The firewall has already authorised this action."
+        )

delego/cli.py

@@ -0,0 +1,150 @@
+"""``delego`` command-line interface.
+
+Covers the human side of the loop: initialise state and keys, inspect the
+policy, review and decide pending approvals, and read/verify the audit ledger.
+The agent side goes through the MCP server (``delego.mcp_server``).
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+import click
+
+from .audit import AuditLog, ensure_keys
+from .config import Paths, ensure_home_gitignore
+from .policy import Policy
+
+_EXAMPLE_POLICY = Path(__file__).resolve().parent.parent / "policy.example.yaml"
+
+
+@click.group()
+@click.option("--home", default=None, help="Delego home dir (default: $DELEGO_HOME or ~/.delego)")
+@click.pass_context
+def cli(ctx: click.Context, home: str | None) -> None:
+    """Delego — a policy & audit firewall for agent actions."""
+    ctx.obj = Paths.resolve(home)
+
+
+@cli.command()
+@click.pass_obj
+def init(paths: Paths) -> None:
+    """Create the home dir, generate signing keys, install an example policy."""
+    paths.home.mkdir(parents=True, exist_ok=True)
+    ensure_home_gitignore(paths.home)
+    ensure_keys(paths.private_key, paths.public_key)
+    if not paths.policy.exists():
+        if _EXAMPLE_POLICY.exists():
+            shutil.copy(_EXAMPLE_POLICY, paths.policy)
+            click.echo(f"Installed example policy at {paths.policy}")
+        else:
+            click.echo("No example policy found; create policy.yaml yourself.")
+    click.echo(f"Initialised delego home at {paths.home}")
+    click.echo(f"Signing key: {paths.private_key}")
+
+
+@cli.command()
+@click.pass_obj
+def home(paths: Paths) -> None:
+    """Print the resolved delego home (where state + policy live)."""
+    click.echo(str(paths.home))
+
+
+@cli.command()
+@click.pass_obj
+def policy(paths: Paths) -> None:
+    """Show the loaded policy summary."""
+    click.echo(f"home:   {paths.home}")
+    p = Policy.load(paths.policy)
+    click.echo(f"policy v{p.version} | default: {p.default}")
+    click.echo("\nforbidden:")
+    for r in p.forbidden:
+        click.echo(f"  - {r.name}: {r.match}")
+    click.echo("\nrules:")
+    for r in p.rules:
+        line = f"  - {r.name} -> {r.decision} | {r.match}"
+        if r.constraints:
+            line += f" | constraints: {r.constraints}"
+        click.echo(line)
+
+
+@cli.command()
+@click.pass_obj
+def pending(paths: Paths) -> None:
+    """List actions awaiting human approval."""
+    from .approval import ApprovalStore
+
+    items = ApprovalStore(paths.approvals).pending()
+    if not items:
+        click.echo("No pending approvals.")
+        return
+    for rec in items:
+        click.echo(f"{rec['id']}  {rec['summary']}")
+        if rec.get("instruction"):
+            click.echo(f"    instruction: {rec['instruction']!r}")
+        click.echo(f"    requested {rec['created_at']}")
+
+
+@cli.command()
+@click.argument("approval_id")
+@click.option("--as", "approver", default="cli", help="Name recorded as approver")
+@click.pass_obj
+def approve(paths: Paths, approval_id: str, approver: str) -> None:
+    """Approve a pending action."""
+    _decide(paths, approval_id, True, approver)
+
+
+@cli.command()
+@click.argument("approval_id")
+@click.option("--as", "approver", default="cli", help="Name recorded as approver")
+@click.pass_obj
+def deny(paths: Paths, approval_id: str, approver: str) -> None:
+    """Deny a pending action."""
+    _decide(paths, approval_id, False, approver)
+
+
+def _decide(paths: Paths, approval_id: str, approved: bool, approver: str) -> None:
+    from .approval import ApprovalStore
+
+    rec = ApprovalStore(paths.approvals).decide(approval_id, approved, approver)
+    if rec is None:
+        click.echo(f"No such approval: {approval_id}")
+        raise SystemExit(1)
+    click.echo(f"{approval_id}: {rec['status']}")
+
+
+@cli.command()
+@click.option("-n", "--lines", default=20, help="Number of receipts to show")
+@click.pass_obj
+def log(paths: Paths, lines: int) -> None:
+    """Show the most recent audit receipts."""
+    audit = AuditLog(paths.audit_log, paths.private_key, paths.public_key)
+    for e in audit.tail(lines):
+        click.echo(
+            f"#{e['seq']} [{e['phase']}/{e['outcome']}] {e['action_summary']}"
+            + (f"  rule={e['rule']}" if e["rule"] else "")
+        )
+        for r in e["reasons"]:
+            click.echo(f"      - {r}")
+
+
+@cli.command()
+@click.pass_obj
+def verify(paths: Paths) -> None:
+    """Verify the audit chain (hashes, linkage, signatures)."""
+    click.echo(f"home: {paths.home}")
+    audit = AuditLog(paths.audit_log, paths.private_key, paths.public_key)
+    ok, problems = audit.verify()
+    if ok:
+        click.echo("Audit chain OK: all receipts intact and signed.")
+    else:
+        click.echo("AUDIT CHAIN FAILED:")
+        for p in problems:
+            click.echo(f"  - {p}")
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    cli()

delego/config.py

@@ -0,0 +1,105 @@
+"""Where state lives on disk, and how to assemble a ``Firewall`` from it.
+
+The delego home directory holds the signing keys, the policy, the audit ledger,
+and the approval queue. ``build_firewall`` is the single wiring point used by
+both the CLI and the MCP server, so they operate on the same state.
+
+Home resolution (see ``Paths.resolve``) lets state be per-user (``~/.delego``)
+or project-scoped and co-located with Claude Code config (``.claude/.delego``).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from .approval import ApprovalStore
+from .audit import AuditLog, ensure_keys
+from .brokers import BrokerAdapter
+from .engine import Firewall
+from .policy import Policy
+
+# State that must never be committed when the home lives inside a repo
+# (e.g. ``.claude/.delego``). ``policy.yaml`` is intentionally left trackable so
+# a team can version and share the policy; secrets and the ledger are not.
+_STATE_GITIGNORE = """\
+# delego runtime state — do not commit secrets or the audit ledger.
+signing_key.pem
+audit.log.jsonl
+approvals.jsonl
+"""
+
+
+@dataclass
+class Paths:
+    home: Path
+
+    @classmethod
+    def resolve(cls, home: str | os.PathLike | None = None) -> "Paths":
+        """Resolve the delego home, in precedence order:
+
+        1. an explicit ``home`` argument (the CLI ``--home`` flag);
+        2. the ``DELEGO_HOME`` environment variable;
+        3. a project-local ``./.claude/.delego`` directory **if it already
+           exists** — only the current directory is checked, never a parent, so
+           the home can't be silently picked up from an ancestor;
+        4. the per-user default ``~/.delego``.
+
+        The MCP server and CLI both resolve through here. Set ``DELEGO_HOME``
+        (the MCP config does) to pin the home explicitly and not depend on the
+        working directory.
+        """
+        if home is not None:
+            return cls(home=Path(home))
+
+        env = os.environ.get("DELEGO_HOME")
+        if env:
+            return cls(home=Path(env))
+
+        project_local = Path.cwd() / ".claude" / ".delego"
+        if project_local.is_dir():
+            return cls(home=project_local)
+
+        return cls(home=Path.home() / ".delego")
+
+    @property
+    def private_key(self) -> Path:
+        return self.home / "signing_key.pem"
+
+    @property
+    def public_key(self) -> Path:
+        return self.home / "signing_key.pub"
+
+    @property
+    def audit_log(self) -> Path:
+        return self.home / "audit.log.jsonl"
+
+    @property
+    def approvals(self) -> Path:
+        return self.home / "approvals.jsonl"
+
+    @property
+    def policy(self) -> Path:
+        return self.home / "policy.yaml"
+
+
+def ensure_home_gitignore(home: str | os.PathLike) -> None:
+    """Drop a ``.gitignore`` in the home so keys/ledger aren't committed when the
+    home lives inside a repo (e.g. ``.claude/.delego``). No-op if one exists."""
+    home = Path(home)
+    home.mkdir(parents=True, exist_ok=True)
+    gitignore = home / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text(_STATE_GITIGNORE, encoding="utf-8")
+
+
+def build_firewall(paths: Paths, broker: BrokerAdapter | None = None) -> Firewall:
+    # Load policy first: a missing/invalid policy fails closed with a clear
+    # message before any state (keys, ledger) is created.
+    policy = Policy.load(paths.policy)
+    ensure_home_gitignore(paths.home)
+    ensure_keys(paths.private_key, paths.public_key)
+    audit = AuditLog(paths.audit_log, paths.private_key, paths.public_key)
+    approvals = ApprovalStore(paths.approvals)
+    return Firewall(policy, audit, approvals, broker=broker)