repoward 0.1.0__py3-none-any.whl

repoward/__init__.py

@@ -0,0 +1 @@
+"""repoward: a GitHub MCP server with enforced guardrails for AI agents."""

repoward/adapters/__init__.py

@@ -0,0 +1 @@
+"""The only code allowed to talk to the network."""

repoward/adapters/ci.py

@@ -0,0 +1,50 @@
+"""Job log download: the one place a redirect is followed, under strict rules."""
+
+import re
+from urllib.parse import urlsplit
+
+import httpx
+
+from repoward.adapters.github import TIMEOUT_SECONDS, USER_AGENT, GitHubClient, repo_path
+from repoward.registry import ToolError
+
+# Observed from a real job-log redirect. An unknown host fails closed; update this if GitHub
+# moves its log storage.
+_LOG_HOST = re.compile(r"productionresultssa\d+\.blob\.core\.windows\.net")
+MAX_LOG_DOWNLOAD_BYTES = 20_000_000
+LOG_TAIL_BYTES = 200_000
+
+
+async def fetch_job_log_tail(client: GitHubClient, repo: str, job_id: int) -> tuple[str, bool]:
+    """Return the end of a job's log, where failures are, and whether anything was cut."""
+    location = await client.get_redirect_location(f"{repo_path(repo)}/actions/jobs/{job_id}/logs")
+    parts = urlsplit(location)
+    if parts.scheme != "https" or not _LOG_HOST.fullmatch(parts.hostname or ""):
+        raise ToolError("GitHub redirected the log download to an unrecognized host.")
+
+    tail = bytearray()
+    total = 0
+    cut = False
+    # A separate client, so the GitHub token can never be sent to the storage host.
+    try:
+        async with (
+            httpx.AsyncClient(
+                follow_redirects=False,
+                timeout=TIMEOUT_SECONDS,
+                headers={"User-Agent": USER_AGENT},
+            ) as http,
+            http.stream("GET", location) as response,
+        ):
+            if response.status_code != 200:
+                raise ToolError("The job log could not be downloaded.")
+            async for chunk in response.aiter_bytes():
+                total += len(chunk)
+                tail += chunk
+                if len(tail) > LOG_TAIL_BYTES:
+                    del tail[: len(tail) - LOG_TAIL_BYTES]
+                    cut = True
+                if total > MAX_LOG_DOWNLOAD_BYTES:
+                    raise ToolError("The job log is too large to download.")
+    except httpx.HTTPError as exc:
+        raise ToolError("The job log could not be downloaded.") from exc
+    return tail.decode("utf-8", "replace"), cut

repoward/adapters/github.py

@@ -0,0 +1,150 @@
+"""GitHub REST client. No tool input ever becomes a URL host; redirects are never followed."""
+
+import json
+import time
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from repoward.registry import ToolError
+
+BASE_URL = "https://api.github.com"
+API_VERSION = "2026-03-10"
+USER_AGENT = "repoward"
+TIMEOUT_SECONDS = 30.0
+MAX_RESPONSE_BYTES = 5_000_000
+JSON_ACCEPT = "application/vnd.github+json"
+TEXT_MATCH_ACCEPT = "application/vnd.github.text-match+json"
+
+
+def repo_path(repo: str) -> str:
+    owner, name = repo.split("/", 1)
+    return f"/repos/{quote(owner, safe='')}/{quote(name, safe='')}"
+
+
+def file_url_path(path: str) -> str:
+    return "/".join(quote(segment, safe="") for segment in path.split("/"))
+
+
+def _wait_seconds(response: httpx.Response) -> int | None:
+    """How long GitHub asks us to wait, if this response is a rate limit."""
+    retry_after = response.headers.get("retry-after", "")
+    if retry_after.isdigit():
+        return int(retry_after)
+    if response.headers.get("x-ratelimit-remaining") == "0":
+        reset = response.headers.get("x-ratelimit-reset", "")
+        return max(1, int(reset) - int(time.time())) if reset.isdigit() else 60
+    return None
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Turn a failed response into a safe message. GitHub's own text is never passed on."""
+    status = response.status_code
+    if 200 <= status < 300:
+        return
+    if status in {403, 429}:
+        wait = _wait_seconds(response)
+        if wait is not None:
+            raise ToolError(f"GitHub rate limit reached. Try again in {wait} seconds.")
+    if status == 403:
+        raise ToolError("GitHub refused the request; the token may lack permission.")
+    if status == 401:
+        raise ToolError("GitHub rejected the token; it may be invalid or expired.")
+    if status == 404:
+        raise ToolError("Not found, or the token cannot access it.")
+    if status in {301, 302, 307, 308}:
+        raise ToolError("GitHub answered with a redirect, which is not followed.")
+    if status == 405:
+        raise ToolError("GitHub says this cannot be done in the current state.")
+    if status == 409:
+        raise ToolError("GitHub reported a conflict; the branch may have moved.")
+    if status == 422:
+        raise ToolError("GitHub rejected the request as invalid.")
+    raise ToolError(f"GitHub returned an unexpected status ({status}).")
+
+
+class GitHubClient:
+    def __init__(self, token: str | None) -> None:
+        self._token = token
+        self._http = httpx.AsyncClient(
+            base_url=BASE_URL,
+            follow_redirects=False,
+            timeout=TIMEOUT_SECONDS,
+            headers={
+                "Accept": JSON_ACCEPT,
+                "X-GitHub-Api-Version": API_VERSION,
+                "User-Agent": USER_AGENT,
+            },
+        )
+
+    def _auth(self) -> dict[str, str]:
+        if not self._token:
+            raise ToolError("GITHUB_TOKEN is not set on the server.")
+        return {"Authorization": f"Bearer {self._token}"}
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def get_json(
+        self, path: str, params: dict[str, Any] | None = None, accept: str = JSON_ACCEPT
+    ) -> Any:
+        """GET a JSON document."""
+        return await self._request("GET", path, params, None, accept)
+
+    async def send_json(self, method: str, path: str, body: dict[str, Any] | None = None) -> Any:
+        """Send a change once. Writes are never retried, so a failure is never doubled."""
+        return await self._request(method, path, None, body, JSON_ACCEPT)
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None,
+        body: dict[str, Any] | None,
+        accept: str,
+    ) -> Any:
+        """Make one request, refusing response bodies over the size cap."""
+        headers = {**self._auth(), "Accept": accept}
+        try:
+            async with self._http.stream(
+                method, path, params=params, json=body, headers=headers
+            ) as response:
+                raise_for_status(response)
+                chunks: list[bytes] = []
+                size = 0
+                async for chunk in response.aiter_bytes():
+                    size += len(chunk)
+                    if size > MAX_RESPONSE_BYTES:
+                        raise ToolError("GitHub's response was too large to process.")
+                    chunks.append(chunk)
+        except httpx.HTTPError as exc:
+            raise ToolError("Could not reach GitHub.") from exc
+        if not chunks:
+            return None
+        try:
+            return json.loads(b"".join(chunks))
+        except ValueError as exc:
+            raise ToolError("GitHub returned a response that could not be read.") from exc
+
+    async def repo_is_private(self, repo: str) -> bool:
+        """Whether a repository is private. Raises if GitHub gives no clear answer."""
+        document = await self.get_json(repo_path(repo))
+        private = document.get("private") if isinstance(document, dict) else None
+        if not isinstance(private, bool):
+            raise ToolError("GitHub returned an unexpected response.")
+        return private
+
+    async def get_redirect_location(self, path: str) -> str:
+        """Request an endpoint that answers 302, returning where it points."""
+        try:
+            response = await self._http.get(path, headers=self._auth())
+        except httpx.HTTPError as exc:
+            raise ToolError("Could not reach GitHub.") from exc
+        if response.status_code != 302:
+            raise_for_status(response)
+            raise ToolError("GitHub did not return the expected redirect.")
+        location = response.headers.get("location")
+        if not location:
+            raise ToolError("GitHub's redirect had no destination.")
+        return str(location)

repoward/approvals/__init__.py

@@ -0,0 +1 @@
+"""Human approval for risky tool calls."""

repoward/approvals/store.py

@@ -0,0 +1,199 @@
+"""SQLite approval store. Each operation is one short transaction, so processes can share it."""
+
+import secrets
+import sqlite3
+import time
+from collections.abc import Callable
+from contextlib import AbstractContextManager
+from dataclasses import dataclass
+from pathlib import Path
+
+from repoward.storage import transaction
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS approvals (
+    id TEXT PRIMARY KEY,
+    ts REAL NOT NULL,
+    principal TEXT NOT NULL,
+    tool TEXT NOT NULL,
+    repo TEXT,
+    args_hash TEXT NOT NULL,
+    args_redacted TEXT NOT NULL,
+    context TEXT NOT NULL,
+    status TEXT NOT NULL CHECK (status IN ('pending','approved','denied','expired','consumed')),
+    decided_by TEXT,
+    decided_at REAL,
+    expires_at REAL NOT NULL,
+    consumed_at REAL
+)
+"""
+_COLUMNS = (
+    "id, ts, principal, tool, repo, args_hash, args_redacted, context, status, "
+    "decided_by, decided_at, expires_at, consumed_at"
+)
+
+
+class ApprovalStoreError(Exception):
+    """The store could not complete an operation. Callers must not execute anything."""
+
+
+class TooManyPendingError(ApprovalStoreError):
+    """This principal already has the maximum number of pending requests."""
+
+
+@dataclass(frozen=True)
+class Approval:
+    id: str
+    ts: float
+    principal: str
+    tool: str
+    repo: str | None
+    args_hash: str
+    args_redacted: str
+    context: str
+    status: str
+    decided_by: str | None
+    decided_at: float | None
+    expires_at: float
+    consumed_at: float | None
+
+
+class ApprovalStore:
+    def __init__(
+        self,
+        path: Path,
+        ttl_seconds: float = 900.0,
+        max_pending_per_principal: int = 20,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        self._path = path
+        self._ttl = ttl_seconds
+        self._max_pending = max_pending_per_principal
+        self._clock = clock
+        with self._transaction() as connection:
+            connection.execute(_SCHEMA)
+
+    def _transaction(self) -> AbstractContextManager[sqlite3.Connection]:
+        return transaction(self._path, ApprovalStoreError)
+
+    def _expire(self, connection: sqlite3.Connection, now: float) -> None:
+        connection.execute(
+            "UPDATE approvals SET status = 'expired' "
+            "WHERE status IN ('pending', 'approved') AND expires_at <= ?",
+            (now,),
+        )
+
+    def request(
+        self,
+        principal: str,
+        tool: str,
+        repo: str | None,
+        args_hash: str,
+        args_redacted: str,
+        context: str,
+    ) -> Approval:
+        """Create a pending request, or return the identical one already waiting."""
+        now = self._clock()
+        with self._transaction() as connection:
+            self._expire(connection, now)
+            row = connection.execute(
+                f"SELECT {_COLUMNS} FROM approvals WHERE principal = ? AND tool = ? "  # noqa: S608
+                "AND repo IS ? AND args_hash = ? AND status = 'pending'",
+                (principal, tool, repo, args_hash),
+            ).fetchone()
+            if row is not None:
+                return Approval(*row)
+            pending = connection.execute(
+                "SELECT COUNT(*) FROM approvals WHERE principal = ? AND status = 'pending'",
+                (principal,),
+            ).fetchone()[0]
+            if pending >= self._max_pending:
+                raise TooManyPendingError("too many pending approval requests")
+            approval = Approval(
+                id=secrets.token_hex(16),
+                ts=now,
+                principal=principal,
+                tool=tool,
+                repo=repo,
+                args_hash=args_hash,
+                args_redacted=args_redacted,
+                context=context,
+                status="pending",
+                decided_by=None,
+                decided_at=None,
+                expires_at=now + self._ttl,
+                consumed_at=None,
+            )
+            connection.execute(
+                f"INSERT INTO approvals ({_COLUMNS}) "  # noqa: S608
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    approval.id,
+                    approval.ts,
+                    approval.principal,
+                    approval.tool,
+                    approval.repo,
+                    approval.args_hash,
+                    approval.args_redacted,
+                    approval.context,
+                    approval.status,
+                    approval.decided_by,
+                    approval.decided_at,
+                    approval.expires_at,
+                    approval.consumed_at,
+                ),
+            )
+            return approval
+
+    def consume(self, principal: str, tool: str, repo: str | None, args_hash: str) -> str | None:
+        """Use up one matching approval, returning its id, or None if there is none.
+
+        Consuming happens before the action runs, so each approval allows at most one attempt.
+        """
+        now = self._clock()
+        with self._transaction() as connection:
+            self._expire(connection, now)
+            row = connection.execute(
+                "SELECT id FROM approvals WHERE principal = ? AND tool = ? AND repo IS ? "
+                "AND args_hash = ? AND status = 'approved' ORDER BY decided_at LIMIT 1",
+                (principal, tool, repo, args_hash),
+            ).fetchone()
+            if row is None:
+                return None
+            cursor = connection.execute(
+                "UPDATE approvals SET status = 'consumed', consumed_at = ? "
+                "WHERE id = ? AND status = 'approved'",
+                (now, row[0]),
+            )
+            return str(row[0]) if cursor.rowcount == 1 else None
+
+    def decide(self, approval_id: str, approved: bool, decided_by: str) -> bool:
+        """Approve or deny a pending request. An approval gets a fresh expiry window."""
+        now = self._clock()
+        status = "approved" if approved else "denied"
+        with self._transaction() as connection:
+            self._expire(connection, now)
+            cursor = connection.execute(
+                "UPDATE approvals SET status = ?, decided_by = ?, decided_at = ?, expires_at = ? "
+                "WHERE id = ? AND status = 'pending'",
+                (status, decided_by, now, now + self._ttl, approval_id),
+            )
+            return cursor.rowcount == 1
+
+    def get(self, approval_id: str) -> Approval | None:
+        with self._transaction() as connection:
+            self._expire(connection, self._clock())
+            row = connection.execute(
+                f"SELECT {_COLUMNS} FROM approvals WHERE id = ?",  # noqa: S608
+                (approval_id,),
+            ).fetchone()
+        return Approval(*row) if row is not None else None
+
+    def list(self, include_all: bool = False) -> list[Approval]:
+        condition = "" if include_all else "WHERE status = 'pending' "
+        with self._transaction() as connection:
+            self._expire(connection, self._clock())
+            rows = connection.execute(
+                f"SELECT {_COLUMNS} FROM approvals {condition}ORDER BY ts"  # noqa: S608
+            ).fetchall()
+        return [Approval(*row) for row in rows]

repoward/audit.py

@@ -0,0 +1,235 @@
+"""Append-only, hash-chained JSONL audit log.
+
+The chain is tamper-evident, not tamper-proof. Anyone who can write the file can recompute a
+plain SHA-256 chain, and no chain alone reveals deleted newest records. An HMAC key the
+attacker cannot read covers the first case; off-host checkpoints cover the second.
+"""
+
+import hashlib
+import hmac
+import json
+import os
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from filelock import FileLock, Timeout
+
+from repoward.canonical import canonical_json
+
+DEFAULT_KEY_ENV = "REPOWARD_AUDIT_HMAC_KEY"
+GENESIS_HASH = "0" * 64
+SCHEMA_VERSION = 1
+_ALG_SHA256 = "sha256"
+_ALG_HMAC = "hmac-sha256"
+_LOCK_TIMEOUT_SECONDS = 5.0
+_TAIL_CHUNK_BYTES = 65_536
+_MIN_KEY_BYTES = 32
+
+
+class AuditWriteError(Exception):
+    """A record could not be durably written."""
+
+
+class AuditKeyError(Exception):
+    """The configured HMAC key is unusable."""
+
+
+def load_hmac_key(env_name: str) -> bytes | None:
+    value = os.environ.get(env_name)
+    if value is None:
+        return None
+    key = value.encode("utf-8")
+    if len(key) < _MIN_KEY_BYTES:
+        raise AuditKeyError(f"{env_name} must be at least {_MIN_KEY_BYTES} bytes")
+    return key
+
+
+def _digest(record: dict[str, Any], key: bytes | None) -> str:
+    body = canonical_json({name: value for name, value in record.items() if name != "hash"})
+    if key is None:
+        return hashlib.sha256(body).hexdigest()
+    return hmac.new(key, body, hashlib.sha256).hexdigest()
+
+
+def _utc_now() -> str:
+    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
+def _read_tail(path: Path) -> dict[str, Any] | None:
+    """Read the last record from disk. A torn final line is refused, never skipped."""
+    if not path.exists() or path.stat().st_size == 0:
+        return None
+    with path.open("rb") as handle:
+        handle.seek(0, os.SEEK_END)
+        position = handle.tell()
+        buffer = b""
+        while position > 0 and buffer.count(b"\n") < 2:
+            step = min(_TAIL_CHUNK_BYTES, position)
+            position -= step
+            handle.seek(position)
+            buffer = handle.read(step) + buffer
+    if not buffer.endswith(b"\n"):
+        raise AuditWriteError("the audit log ends with an incomplete record")
+    last_line = buffer[:-1].rsplit(b"\n", 1)[-1]
+    try:
+        record = json.loads(last_line)
+    except ValueError as exc:
+        raise AuditWriteError("the last audit record is not valid JSON") from exc
+    if not isinstance(record, dict):
+        raise AuditWriteError("the last audit record is not an object")
+    return record
+
+
+class AuditLog:
+    def __init__(self, path: Path, hmac_key: bytes | None = None) -> None:
+        self._path = path
+        self._key = hmac_key
+        self._alg = _ALG_SHA256 if hmac_key is None else _ALG_HMAC
+        self._lock = FileLock(f"{path}.lock", timeout=_LOCK_TIMEOUT_SECONDS)
+
+    def append(self, fields: dict[str, Any]) -> dict[str, Any]:
+        """Durably append one record, chained to whatever is on disk now.
+
+        The tail is re-read every time because other processes share this file.
+        """
+        try:
+            with self._lock:
+                tail = _read_tail(self._path)
+                if tail is not None and tail.get("alg") != self._alg:
+                    raise AuditWriteError(
+                        "the audit log uses a different hash mode; start a new log to change it"
+                    )
+                record: dict[str, Any] = {
+                    **fields,
+                    "schema_version": SCHEMA_VERSION,
+                    "seq": 1 if tail is None else int(tail["seq"]) + 1,
+                    "ts": _utc_now(),
+                    "alg": self._alg,
+                    "prev_hash": GENESIS_HASH if tail is None else str(tail["hash"]),
+                }
+                record["hash"] = _digest(record, self._key)
+                line = canonical_json(record) + b"\n"
+                with self._path.open("ab") as handle:
+                    handle.write(line)
+                    handle.flush()
+                    os.fsync(handle.fileno())
+                return record
+        except AuditWriteError:
+            raise
+        except (OSError, Timeout, KeyError, TypeError, ValueError) as exc:
+            raise AuditWriteError(f"cannot write audit record: {type(exc).__name__}") from exc
+
+
+@dataclass
+class VerifyReport:
+    records: int = 0
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    tip_seq: int = 0
+    tip_hash: str = GENESIS_HASH
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+def _load_anchors(path: Path, report: VerifyReport) -> list[dict[str, Any]]:
+    anchors: list[dict[str, Any]] = []
+    try:
+        for raw in path.read_text(encoding="utf-8").splitlines():
+            anchor = json.loads(raw)
+            if not isinstance(anchor, dict) or "seq" not in anchor or "hash" not in anchor:
+                raise ValueError
+            anchors.append(anchor)
+    except (OSError, ValueError):
+        report.errors.append("the anchor file cannot be read")
+    return anchors
+
+
+def _record_error(record: Any, raw: bytes, key: bytes | None, prev: str, number: int) -> str | None:
+    """Return why a parsed line breaks the chain, or None if it is sound."""
+    if not isinstance(record, dict) or canonical_json(record) != raw:
+        return "record is not in canonical form"
+    expected_alg = _ALG_SHA256 if key is None else _ALG_HMAC
+    if record.get("alg") != expected_alg:
+        return f"hash mode is {record.get('alg')!r}, expected {expected_alg!r}"
+    if record.get("seq") != number:
+        return "sequence number is wrong"
+    if record.get("prev_hash") != prev:
+        return "does not chain to the previous record"
+    claimed = record.get("hash")
+    if not isinstance(claimed, str) or not hmac.compare_digest(claimed, _digest(record, key)):
+        return "hash does not match its contents"
+    return None
+
+
+def verify_log(
+    path: Path, hmac_key: bytes | None = None, anchor_path: Path | None = None
+) -> VerifyReport:
+    """Check the whole chain, stopping at the first break."""
+    report = VerifyReport()
+    try:
+        raw_lines = path.read_bytes().split(b"\n")
+    except OSError as exc:
+        report.errors.append(f"cannot read audit log: {exc.strerror}")
+        return report
+    if raw_lines[-1] != b"":
+        report.errors.append(f"line {len(raw_lines)}: incomplete final record")
+        return report
+
+    seen_hashes: dict[int, str] = {}
+    open_calls: dict[str, int] = {}
+    previous = GENESIS_HASH
+    for number, raw in enumerate(raw_lines[:-1], start=1):
+        try:
+            record = json.loads(raw)
+            problem = _record_error(record, raw, hmac_key, previous, number)
+        except (ValueError, TypeError):
+            problem = "not valid JSON"
+        if problem is not None:
+            report.errors.append(f"line {number}: {problem}")
+            return report
+        previous = record["hash"]
+        seen_hashes[number] = previous
+        report.records = report.tip_seq = number
+        report.tip_hash = previous
+        request_id = str(record.get("request_id"))
+        if record.get("event") == "tool_call_decision" and record.get("decision") == "allow":
+            open_calls[request_id] = number
+        elif record.get("event") == "tool_call_outcome":
+            open_calls.pop(request_id, None)
+
+    for request_id, number in open_calls.items():
+        report.warnings.append(
+            f"line {number}: allowed call {request_id} has no outcome; its result is unknown"
+        )
+    if anchor_path is None:
+        report.warnings.append("no anchor file given, so deleted newest records go undetected")
+    else:
+        for anchor in _load_anchors(anchor_path, report):
+            seq = anchor["seq"]
+            if seq not in seen_hashes:
+                report.errors.append(f"anchor at seq {seq}: record is missing (log truncated)")
+            elif seen_hashes[seq] != anchor["hash"]:
+                report.errors.append(f"anchor at seq {seq}: hash does not match")
+    return report
+
+
+def write_checkpoint(path: Path, out: Path, hmac_key: bytes | None = None) -> VerifyReport:
+    """Verify the log, then append its tip to an anchor file meant to be stored off-host."""
+    report = verify_log(path, hmac_key, anchor_path=out if out.exists() else None)
+    if report.ok and report.records == 0:
+        report.errors.append("the audit log is empty")
+    if not report.ok:
+        return report
+    line = canonical_json({"seq": report.tip_seq, "hash": report.tip_hash, "ts": _utc_now()})
+    try:
+        with out.open("ab") as handle:
+            handle.write(line + b"\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+    except OSError as exc:
+        report.errors.append(f"cannot write anchor file: {exc.strerror}")
+    return report

repoward/canonical.py

@@ -0,0 +1,20 @@
+"""One invariant byte form for everything that gets hashed."""
+
+import hashlib
+import json
+from typing import Any
+
+
+def canonical_json(value: Any) -> bytes:
+    """Serialize to sorted, compact UTF-8 JSON.
+
+    Over this project's data (ASCII keys, no floats) the output matches RFC 8785.
+    """
+    text = json.dumps(
+        value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False
+    )
+    return text.encode("utf-8", "surrogatepass")
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()