repoward 0.1.0__py3-none-any.whl

repoward/catalog.py

@@ -0,0 +1,29 @@
+"""Every tool name this project defines, with its risk class.
+
+Policy files are validated against this catalog, including tools not implemented yet.
+"""
+
+from enum import StrEnum
+
+
+class RiskClass(StrEnum):
+    READ = "read"
+    WRITE = "write"
+    DANGEROUS = "dangerous"
+
+
+TOOL_CATALOG: dict[str, RiskClass] = {
+    "ping": RiskClass.READ,
+    "github_list_issues": RiskClass.READ,
+    "github_get_issue": RiskClass.READ,
+    "github_search_code": RiskClass.READ,
+    "github_get_file": RiskClass.READ,
+    "ci_get_status": RiskClass.READ,
+    "ci_get_job_logs": RiskClass.READ,
+    "github_create_branch": RiskClass.WRITE,
+    "github_commit_files": RiskClass.WRITE,
+    "github_create_pull_request": RiskClass.WRITE,
+    "github_comment": RiskClass.WRITE,
+    "github_merge_pull_request": RiskClass.DANGEROUS,
+    "github_delete_branch": RiskClass.DANGEROUS,
+}

repoward/cli.py

@@ -0,0 +1,391 @@
+"""Command line interface."""
+
+import argparse
+import getpass
+import sys
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from importlib.metadata import version
+from pathlib import Path
+
+from repoward.approvals.store import Approval, ApprovalStore, ApprovalStoreError
+from repoward.audit import (
+    DEFAULT_KEY_ENV,
+    AuditKeyError,
+    AuditLog,
+    AuditWriteError,
+    VerifyReport,
+    load_hmac_key,
+    verify_log,
+    write_checkpoint,
+)
+from repoward.flow import FlowStore, FlowStoreError
+from repoward.policy.loader import PolicyError, load_policy
+from repoward.sanitize import display_safe
+from repoward.server import run_stdio
+from repoward.setup import (
+    APPROVALS_FILE,
+    AUDIT_FILE,
+    FLOW_FILE,
+    POLICY_FILE,
+    STARTER_ROLES,
+    client_config,
+    default_dir,
+    write_starter,
+)
+
+
+def _error(message: str) -> None:
+    print(f"repoward: {message}", file=sys.stderr)
+
+
+def _print_policy_error(path: Path, exc: PolicyError) -> None:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeDecodeError):
+        lines = []
+    for issue in exc.issues:
+        where = f"{path}:{issue.line}:{issue.column}" if issue.line else str(path)
+        print(f"{where}: {issue.message}", file=sys.stderr)
+        if issue.line and issue.line <= len(lines):
+            print(f"    {lines[issue.line - 1]}", file=sys.stderr)
+            if issue.column:
+                print(f"    {' ' * (issue.column - 1)}^", file=sys.stderr)
+
+
+def _print_report(report: VerifyReport) -> int:
+    for warning in report.warnings:
+        print(f"warning: {warning}")
+    for error in report.errors:
+        print(f"error: {error}")
+    if report.ok:
+        print(f"OK: {report.records} records, tip {report.tip_hash}")
+        return 0
+    print(f"FAILED after {report.records} valid records")
+    return 1
+
+
+def _validate_policy(args: argparse.Namespace) -> int:
+    path = args.path or default_dir() / POLICY_FILE
+    try:
+        compiled = load_policy(path)
+    except PolicyError as exc:
+        _print_policy_error(path, exc)
+        return 1
+    print(f"OK: {len(compiled.roles)} roles, sha256 {compiled.sha256}")
+    return 0
+
+
+def _serve(args: argparse.Namespace) -> int:
+    directory = args.dir or default_dir()
+    policy_path = args.policy or directory / POLICY_FILE
+    if not policy_path.exists():
+        _error(f"no policy at {policy_path}. Create one with: repoward init --repo owner/name")
+        return 1
+    try:
+        compiled = load_policy(policy_path)
+        key = load_hmac_key(DEFAULT_KEY_ENV)
+    except PolicyError as exc:
+        _print_policy_error(policy_path, exc)
+        return 1
+    except AuditKeyError as exc:
+        _error(str(exc))
+        return 1
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+        run_stdio(
+            compiled,
+            args.audit or directory / AUDIT_FILE,
+            args.approvals or directory / APPROVALS_FILE,
+            args.flow or directory / FLOW_FILE,
+            key,
+        )
+    except OSError as exc:
+        _error(f"cannot use {directory}: {exc.strerror}")
+        return 1
+    except (ApprovalStoreError, FlowStoreError) as exc:
+        _error(str(exc))
+        return 1
+    return 0
+
+
+def _init(args: argparse.Namespace) -> int:
+    directory = args.dir or default_dir()
+    try:
+        path = write_starter(directory, args.repo, args.role)
+    except FileExistsError:
+        _error(f"{directory / POLICY_FILE} already exists, and it was left unchanged")
+        return 1
+    except PolicyError as exc:
+        for issue in exc.issues:
+            _error(issue.message)
+        return 1
+    except OSError as exc:
+        _error(f"cannot write to {directory}: {exc.strerror}")
+        return 1
+    print(f"Created {path}, with role '{args.role}'.\n")
+    print("Next steps:\n")
+    print("1. Create a fine-grained GitHub token limited to those repositories:")
+    print("   https://github.com/settings/personal-access-tokens/new\n")
+    print("2. Add this to your MCP client's config, replacing <your-token>:\n")
+    print(client_config(directory))
+    print(
+        "\n3. Protect your default branch with a ruleset that has no bypass for the token's owner."
+    )
+    print("\nImportant: this is not a security boundary for an agent that has a shell running as")
+    print(
+        "the same OS user. It could use git directly, read the token or approve its own requests."
+    )
+    print("Separate them, or give the agent MCP tools only. Details:")
+    print("https://github.com/Sanoy24/repoward/blob/main/docs/THREAT_MODEL.md")
+    return 0
+
+
+def _audit_key(args: argparse.Namespace) -> bytes | None:
+    return load_hmac_key(args.key_env) if args.key_env else None
+
+
+def _audit_verify(args: argparse.Namespace) -> int:
+    try:
+        path = args.file or default_dir() / AUDIT_FILE
+        return _print_report(verify_log(path, _audit_key(args), args.anchor))
+    except AuditKeyError as exc:
+        _error(str(exc))
+        return 1
+
+
+def _audit_checkpoint(args: argparse.Namespace) -> int:
+    try:
+        path = args.file or default_dir() / AUDIT_FILE
+        return _print_report(write_checkpoint(path, args.out, _audit_key(args)))
+    except AuditKeyError as exc:
+        _error(str(exc))
+        return 1
+
+
+def _in_home(path: Path | None, filename: str) -> Path:
+    """Use the given path, or a file in the home directory, which is created if needed."""
+    if path is not None:
+        return path
+    directory = default_dir()
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory / filename
+
+
+def _approval_store(args: argparse.Namespace) -> ApprovalStore:
+    return ApprovalStore(_in_home(args.db, APPROVALS_FILE))
+
+
+def _flow_store(args: argparse.Namespace) -> FlowStore:
+    return FlowStore(_in_home(args.db, FLOW_FILE))
+
+
+def _audit_path(args: argparse.Namespace) -> Path:
+    return _in_home(args.audit, AUDIT_FILE)
+
+
+def _when(timestamp: float | None) -> str:
+    if timestamp is None:
+        return "-"
+    return datetime.fromtimestamp(timestamp, UTC).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+
+def _print_approval(approval: Approval) -> None:
+    """Print verified fields first. Everything is cleaned, so text cannot spoof the terminal."""
+    print(f"Request:    {display_safe(approval.id)}")
+    print(f"Status:     {display_safe(approval.status)}")
+    print(f"Tool:       {display_safe(approval.tool)}")
+    print(f"Repository: {display_safe(approval.repo or '-')}")
+    print(f"Requested:  {display_safe(approval.principal)} at {_when(approval.ts)}")
+    print(f"Expires:    {_when(approval.expires_at)}")
+    print(f"Arguments:  {display_safe(approval.args_redacted)}")
+    if approval.decided_by:
+        print(f"Decided:    {display_safe(approval.decided_by)} at {_when(approval.decided_at)}")
+    if approval.context:
+        print("From GitHub (untrusted, may be written by anyone):")
+        for line in display_safe(approval.context).splitlines():
+            print(f"  | {line}")
+
+
+def _approvals_list(args: argparse.Namespace) -> int:
+    items = _approval_store(args).list(include_all=args.all)
+    if not items:
+        print("No requests.")
+    for item in items:
+        print(
+            f"{display_safe(item.id)}  {display_safe(item.status)}  {display_safe(item.tool)}  "
+            f"{display_safe(item.repo or '-')}  expires {_when(item.expires_at)}"
+        )
+    return 0
+
+
+def _approvals_show(args: argparse.Namespace) -> int:
+    approval = _approval_store(args).get(args.id)
+    if approval is None:
+        _error("no such request")
+        return 1
+    _print_approval(approval)
+    return 0
+
+
+def _decide(args: argparse.Namespace, approved: bool) -> int:
+    """Audit first: if the decision cannot be recorded, it is not made."""
+    store = _approval_store(args)
+    approval = store.get(args.id)
+    if approval is None:
+        _error("no such request")
+        return 1
+    if approval.status != "pending":
+        _error(f"this request is {display_safe(approval.status)}, not pending")
+        return 1
+    decided_by = getpass.getuser()
+    try:
+        audit = AuditLog(_audit_path(args), load_hmac_key(DEFAULT_KEY_ENV))
+        audit.append(
+            {
+                "event": "approval_decision",
+                "approval_id": approval.id,
+                "decision": "approved" if approved else "denied",
+                "decided_by": decided_by,
+                "principal": approval.principal,
+                "tool": approval.tool,
+                "repo": approval.repo,
+                "args_hash": approval.args_hash,
+            }
+        )
+    except (AuditWriteError, AuditKeyError) as exc:
+        _error(f"not decided, because the decision could not be audited: {exc}")
+        return 1
+    if not store.decide(approval.id, approved, decided_by):
+        _error("the request changed before it could be decided")
+        return 1
+    _print_approval(store.get(approval.id) or approval)
+    return 0
+
+
+def _approvals_approve(args: argparse.Namespace) -> int:
+    return _decide(args, approved=True)
+
+
+def _approvals_deny(args: argparse.Namespace) -> int:
+    return _decide(args, approved=False)
+
+
+def _flow_status(args: argparse.Namespace) -> int:
+    labels = _flow_store(args).active()
+    if not labels:
+        print("No active labels.")
+    for label in labels:
+        print(
+            f"{display_safe(label.principal)}  {display_safe(label.kind)}  "
+            f"{display_safe(label.source)}  expires {_when(label.expires_at)}"
+        )
+    return 0
+
+
+def _flow_reset(args: argparse.Namespace) -> int:
+    """Audit first: if the reset cannot be recorded, it does not happen."""
+    store = _flow_store(args)
+    try:
+        AuditLog(_audit_path(args), load_hmac_key(DEFAULT_KEY_ENV)).append(
+            {
+                "event": "flow_reset",
+                "principal": args.principal,
+                "decided_by": getpass.getuser(),
+            }
+        )
+    except (AuditWriteError, AuditKeyError) as exc:
+        _error(f"not reset, because the reset could not be audited: {exc}")
+        return 1
+    print(f"Cleared {store.reset(args.principal)} labels.")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="repoward", description=__doc__)
+    parser.add_argument("--version", action="version", version=version("repoward"))
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    init = commands.add_parser("init", help="create a safe starter policy")
+    init.add_argument(
+        "--repo", action="append", required=True, help="owner/name to allow; repeatable"
+    )
+    init.add_argument(
+        "--role", choices=STARTER_ROLES, default="reader", help="role for this server"
+    )
+    init.add_argument("--dir", type=Path, help="directory for repoward's files")
+    init.set_defaults(run=_init)
+
+    serve = commands.add_parser("serve", help="serve MCP over stdio")
+    serve.add_argument("--dir", type=Path, help="directory for repoward's files")
+    serve.add_argument("--policy", type=Path, help="policy YAML file")
+    serve.add_argument("--audit", type=Path, help="audit JSONL file")
+    serve.add_argument("--approvals", type=Path, help="approvals database")
+    serve.add_argument("--flow", type=Path, help="flow guard database")
+    serve.set_defaults(run=_serve)
+
+    validate = commands.add_parser("validate-policy", help="check a policy file")
+    validate.add_argument("path", type=Path, nargs="?")
+    validate.set_defaults(run=_validate_policy)
+
+    audit = commands.add_parser("audit", help="work with audit logs")
+    audit_commands = audit.add_subparsers(dest="audit_command", required=True)
+
+    verify = audit_commands.add_parser("verify", help="check a log's hash chain")
+    verify.add_argument("file", type=Path, nargs="?")
+    verify.add_argument("--anchor", type=Path, help="anchor file from audit checkpoint")
+    verify.add_argument("--key-env", help="environment variable holding the HMAC key")
+    verify.set_defaults(run=_audit_verify)
+
+    checkpoint = audit_commands.add_parser("checkpoint", help="record the log's current tip")
+    checkpoint.add_argument("file", type=Path, nargs="?")
+    checkpoint.add_argument("--out", type=Path, required=True, help="anchor file to append to")
+    checkpoint.add_argument("--key-env", help="environment variable holding the HMAC key")
+    checkpoint.set_defaults(run=_audit_checkpoint)
+
+    approvals = commands.add_parser("approvals", help="review requests waiting for a human")
+    approvals.add_argument("--db", type=Path, help="approvals database")
+    approval_commands = approvals.add_subparsers(dest="approvals_command", required=True)
+
+    listing = approval_commands.add_parser("list", help="show pending requests")
+    listing.add_argument("--all", action="store_true", help="include decided requests")
+    listing.set_defaults(run=_approvals_list)
+
+    show = approval_commands.add_parser("show", help="show one request in full")
+    show.add_argument("id")
+    show.set_defaults(run=_approvals_show)
+
+    for name, handler in (("approve", _approvals_approve), ("deny", _approvals_deny)):
+        decision = approval_commands.add_parser(name, help=f"{name} a request")
+        decision.add_argument("id")
+        decision.add_argument("--audit", type=Path, help="audit JSONL file")
+        decision.set_defaults(run=handler)
+
+    flow = commands.add_parser(
+        "flow", help="inspect or clear what agents are marked as having read"
+    )
+    flow.add_argument("--db", type=Path, help="flow guard database")
+    flow_commands = flow.add_subparsers(dest="flow_command", required=True)
+
+    status = flow_commands.add_parser("status", help="show active labels")
+    status.set_defaults(run=_flow_status)
+
+    reset = flow_commands.add_parser("reset", help="clear labels so writes are allowed again")
+    reset.add_argument("--principal", help="only this principal (default: everyone)")
+    reset.add_argument("--audit", type=Path, help="audit JSONL file")
+    reset.set_defaults(run=_flow_reset)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line interface and return an exit code."""
+    args = _build_parser().parse_args(argv)
+    try:
+        return int(args.run(args))
+    except (ApprovalStoreError, FlowStoreError) as exc:
+        _error(str(exc))
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

repoward/flow.py

@@ -0,0 +1,239 @@
+"""Flow guard: decide each write by what this principal has already read.
+
+Per-tool rules cannot stop the toxic flow, where a malicious public issue steers an agent to
+read a private repository and publish it, because each call is allowed on its own. This guard
+remembers two facts taken from GitHub, not from scanning content:
+
+- private_read: the principal read content from a private repository.
+- untrusted_input: the principal read text from an author outside the trusted associations.
+
+State is keyed by principal and survives restarts. Only a person can clear it, through the
+CLI. No tool can, and no agent-supplied value can start a clean slate, because an injected
+agent would simply do that while the data stayed in its context.
+
+The limits: this only sees this server's tools, and content can stay in an agent's context after
+a label expires.
+"""
+
+import time
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+import anyio.to_thread
+
+from repoward.policy.engine import Decision, Effect
+from repoward.policy.models import FlowGuardRules
+from repoward.storage import transaction
+
+PRIVATE_READ = "private_read"
+UNTRUSTED_INPUT = "untrusted_input"
+TOUCHED_REPO = "touched_repo"
+_VISIBILITY_TTL_SECONDS = 60.0
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS flow_labels (
+    principal TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    source TEXT NOT NULL,
+    first_seen REAL NOT NULL,
+    expires_at REAL NOT NULL,
+    PRIMARY KEY (principal, kind, source)
+)
+"""
+
+
+class FlowStoreError(Exception):
+    """Flow state could not be read or saved. Callers must fail closed."""
+
+
+@dataclass(frozen=True)
+class Taint:
+    """Text a tool returned from someone. No association means treat as untrusted."""
+
+    source: str
+    association: str | None = None
+
+
+@dataclass(frozen=True)
+class FlowLabel:
+    principal: str
+    kind: str
+    source: str
+    first_seen: float
+    expires_at: float
+
+
+class FlowStore:
+    def __init__(self, path: Path, clock: Callable[[], float] = time.time) -> None:
+        self._path = path
+        self._clock = clock
+        with transaction(self._path, FlowStoreError) as connection:
+            connection.execute(_SCHEMA)
+
+    def add(self, principal: str, kind: str, source: str, window_seconds: float) -> bool:
+        """Set or extend a label. Returns True if it was not already active."""
+        now = self._clock()
+        with transaction(self._path, FlowStoreError) as connection:
+            connection.execute("DELETE FROM flow_labels WHERE expires_at <= ?", (now,))
+            active = connection.execute(
+                "SELECT 1 FROM flow_labels WHERE principal = ? AND kind = ? AND source = ?",
+                (principal, kind, source),
+            ).fetchone()
+            if active:
+                connection.execute(
+                    "UPDATE flow_labels SET expires_at = ? "
+                    "WHERE principal = ? AND kind = ? AND source = ?",
+                    (now + window_seconds, principal, kind, source),
+                )
+                return False
+            connection.execute(
+                "INSERT INTO flow_labels (principal, kind, source, first_seen, expires_at) "
+                "VALUES (?, ?, ?, ?, ?)",
+                (principal, kind, source, now, now + window_seconds),
+            )
+            return True
+
+    def active(self, principal: str | None = None) -> list[FlowLabel]:
+        now = self._clock()
+        with transaction(self._path, FlowStoreError) as connection:
+            connection.execute("DELETE FROM flow_labels WHERE expires_at <= ?", (now,))
+            query = "SELECT principal, kind, source, first_seen, expires_at FROM flow_labels"
+            params: tuple[str, ...] = ()
+            if principal is not None:
+                query += " WHERE principal = ?"
+                params = (principal,)
+            rows = connection.execute(query + " ORDER BY first_seen", params).fetchall()
+        return [FlowLabel(*row) for row in rows]
+
+    def reset(self, principal: str | None = None) -> int:
+        """Clear labels. Only the operator CLI calls this."""
+        with transaction(self._path, FlowStoreError) as connection:
+            if principal is None:
+                cursor = connection.execute("DELETE FROM flow_labels")
+            else:
+                cursor = connection.execute(
+                    "DELETE FROM flow_labels WHERE principal = ?", (principal,)
+                )
+            return cursor.rowcount
+
+
+class FlowGuard:
+    def __init__(
+        self,
+        rules: FlowGuardRules,
+        store: FlowStore,
+        repo_is_private: Callable[[str], Awaitable[bool]],
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._rules = rules
+        self._store = store
+        self._repo_is_private = repo_is_private
+        self._clock = clock
+        self._window = rules.window_minutes * 60.0
+        self._visibility: dict[str, tuple[bool, float]] = {}
+
+    async def _is_private(self, repo: str) -> bool | None:
+        """Repository visibility, or None if GitHub could not say."""
+        key = repo.casefold()
+        cached = self._visibility.get(key)
+        if cached is not None and self._clock() < cached[1]:
+            return cached[0]
+        try:
+            private = await self._repo_is_private(repo)
+        except Exception:
+            return None
+        self._visibility[key] = (private, self._clock() + _VISIBILITY_TTL_SECONDS)
+        return private
+
+    async def _active(self, principal: str) -> list[FlowLabel]:
+        return await anyio.to_thread.run_sync(self._store.active, principal)
+
+    async def _add(self, principal: str, kind: str, source: str) -> bool:
+        return await anyio.to_thread.run_sync(
+            self._store.add, principal, kind, source, self._window
+        )
+
+    async def check_write(self, principal: str, repo: str | None) -> Decision | None:
+        """Decide a write. None means the guard has no objection. Fails closed."""
+        try:
+            labels = await self._active(principal)
+            kinds = {label.kind for label in labels}
+            if (
+                repo is not None
+                and PRIVATE_READ in kinds
+                and await self._is_private(repo) is not True
+            ):
+                # An unknown target is treated as public.
+                if self._rules.on_private_to_public == "deny":
+                    return Decision(
+                        Effect.DENY,
+                        "flow.private_to_public",
+                        "This agent has read private content, so it cannot write to a public "
+                        "repository. A person can clear this with repoward flow reset.",
+                    )
+                return Decision(
+                    Effect.APPROVAL_REQUIRED,
+                    "flow.private_to_public",
+                    "This write needs human approval because the agent has read private content.",
+                )
+            if self._rules.single_repo and repo is not None:
+                touched = [label.source for label in labels if label.kind == TOUCHED_REPO]
+                if touched and touched[0] != repo.casefold():
+                    return Decision(
+                        Effect.DENY,
+                        "flow.single_repo",
+                        "This agent is limited to one repository until a person resets it.",
+                    )
+                await self._add(principal, TOUCHED_REPO, repo.casefold())
+            if UNTRUSTED_INPUT in kinds:
+                if self._rules.on_untrusted_author == "deny":
+                    return Decision(
+                        Effect.DENY,
+                        "flow.untrusted_author",
+                        "This agent has read text from an untrusted author, so it cannot write. "
+                        "A person can clear this with repoward flow reset.",
+                    )
+                return Decision(
+                    Effect.APPROVAL_REQUIRED,
+                    "flow.untrusted_author",
+                    "This write needs human approval because the agent read untrusted text.",
+                )
+        except FlowStoreError:
+            return Decision(
+                Effect.DENY,
+                "flow.unavailable",
+                "This write was blocked because the flow guard's state is unavailable.",
+            )
+        return None
+
+    async def record_read(
+        self, principal: str, repo: str | None, taints: Sequence[Taint]
+    ) -> list[tuple[str, str]]:
+        """Save what was just read, before it is returned. Raises FlowStoreError on failure."""
+        added: list[tuple[str, str]] = []
+
+        async def add(kind: str, source: str) -> None:
+            if await self._add(principal, kind, source):
+                added.append((kind, source))
+
+        if repo is not None:
+            # A repository of unknown visibility is treated as private.
+            if await self._is_private(repo) is not False:
+                await add(PRIVATE_READ, repo.casefold())
+            if self._rules.single_repo:
+                await add(TOUCHED_REPO, repo.casefold())
+        trusted = set(self._rules.trusted_associations)
+        for taint in taints:
+            if taint.association not in trusted:
+                await add(UNTRUSTED_INPUT, taint.source)
+        return added
+
+    async def describe(self, principal: str) -> str:
+        """Why this principal's writes are restricted, for the person reviewing an approval."""
+        labels = await self._active(principal)
+        lines = [
+            f"Flow guard: {label.kind} from {label.source}"
+            for label in labels
+            if label.kind != TOUCHED_REPO
+        ]
+        return "\n".join(lines)