Files
skills/orchestrator/client/approval.py
T
Kevin Veen-BirkenbachandClaude Opus 5.5 b95af2a8e0 feat(orchestrator): verify hub approvals from an MCP record
Sandboxed agents cannot reach the hub on localhost:8737 (refused directly, timeout through the sandbox proxy), so approval.py verify failed and every kvb-git-diff approval fell back to the chat question (Quality: 3 reviews on 2026-11-17). The MCP tools review_status and review_wait, which run outside the sandbox, now also return the review's passkey proof, the record the HTTP proof route already served; approval.py verify --record <file> reads that object instead of fetching it and checks the signature against the pinned approvers, the replay store and the local tree as before, so trust stays with the operator's passkey, not the transport. kvb-git-diff names the sandbox path.

🎯 Fix: 93 %
💥 Break: 3 %
💸 Tokens: 100 %
⏱️ Velocity: 100 %
🛡️ Security: 100 %
🏆 Score: 90
🚦 Gate: ✅ 90/5, tokens and velocity <= 100, security 100 %

Created-with: https://s.veen.world/skills
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:13:45 +00:00

176 lines
8.3 KiB
Python
Executable File

#!/usr/bin/env python3
"""Args:
pin --port <port> --approvers <file> --credential <blob>: pins the passkey
that the Agent Orchestrator settings panel registered (the blob it shows) in
<file>, written with mode 0600. Run it on the host, outside every
sandbox, e.g. --approvers ~/.config/kvb-orchestrator/approvers.json.
verify --port <port> --approvers <file> --replay <file> --review <id>
--gate <pass|fail> [--record <file>]: run in the worktree right before
the commit; fetches the review's signature from the Agent Orchestrator
on 127.0.0.1:<port>, or reads it from <file>, the JSON object the MCP
tool review_wait or review_status answered, where a sandbox blocks
that port; checks it against the repository, worktree, branch and
the tree git write-tree prints, as this process sees them.
request --port <port> --title <subject> --page <file> --notes <file>
--gate <pass|fail> --score <line> --agent <name> [--rules <dir>]:
run in the worktree; asks the operator to approve the staged tree,
with the repository, worktree, branch and tree as git prints them
here, the notes file's text (refused past NOTES_LIMIT characters),
and the diff of the tree git write-tree prints against HEAD
(staged_diff.tree_diff, secrets masked per the MEDUSA rules under
<dir>, by default those of the pipx install) with the sealed clear
patches of its masked files apart; without either when the body
would pass DIFF_BODY_LIMIT.
Returns:
pin: exit code 0 and the pinned credential on stdout; 1 and the reason
on stderr when the blob is no valid registration.
request: exit code 0 and the hub's {"id", "status", "url"} on stdout;
1 and the reason on stderr.
verify: exit code 0 when a pinned key signed this exact commit; 1 and
the reason on stderr otherwise. Commit only on 0.
"""
from __future__ import annotations
import argparse
import json
import sys
import time
import urllib.request
from pathlib import Path
import staged_diff
from hub_api import GUARD, SLACK, base_url, load
from hub_limits import DIFF_BODY_LIMIT, NOTES_LIMIT
from passkey import attested, b64decode
from signing import ALGORITHMS, ID, Refused, origin_of, review_item
from verifier import Trust, check, pin
def git(cwd: Path, args: list[str]) -> str:
try:
return staged_diff.git(cwd, args, None).decode("utf-8", "surrogateescape").strip()
except staged_diff.DiffError as error:
raise Refused(str(error)) from error
def staged(cwd: Path, review_id: str) -> dict:
repo = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"])
worktree = git(cwd, ["rev-parse", "--show-toplevel"])
branch = git(cwd, ["symbolic-ref", "--short", "HEAD"])
return review_item(review_id, repo, worktree, branch, git(cwd, ["write-tree"]))
def fetch(port: int, path: str) -> dict:
request = urllib.request.Request(f"{base_url(port)}{path}", headers=GUARD)
try:
data = load(request, SLACK)
except (OSError, ValueError) as error:
raise Refused(f"the Agent Orchestrator did not answer: {error}") from error
if not isinstance(data, dict):
raise Refused("the Agent Orchestrator answered no object")
return data
def recorded(path: Path, review_id: str) -> dict:
try:
data = json.loads(path.read_text(encoding="utf-8"))
except (OSError, ValueError, RecursionError) as error:
raise Refused(f"the record {path} cannot be read as JSON: {error}") from error
if not isinstance(data, dict) or data.get("id") != review_id:
raise Refused(f"the record {path} is not review {review_id}")
return data
def verify_commit(args: argparse.Namespace) -> str:
review = recorded(args.record, args.review) if args.record else fetch(args.port, f"/api/reviews/{args.review}")
if review.get("status") != "approved":
raise Refused(f"the review is {review.get('status')}, not approved")
item = staged(Path.cwd(), args.review)
check(review.get("proof"), item, args.gate, Trust(approvers=args.approvers, replay=args.replay, origin=origin_of(args.port)), time.time())
return f"verified: the operator signed review {args.review}, tree {item['tree']} on {item['branch']} in {item['worktree']}"
def review_body(arguments: dict) -> bytes:
call = {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "review_request", "arguments": arguments}}
return json.dumps(call, ensure_ascii=False).encode("utf-8")
def request_review(args: argparse.Namespace) -> str:
cwd = Path.cwd()
item = staged(cwd, "0" * 16)
try:
notes = args.notes.read_text(encoding="utf-8")
diff, sealed = staged_diff.tree_diff(cwd, item["tree"], args.rules or staged_diff.rules_root())
except (OSError, ValueError, staged_diff.DiffError) as error:
raise Refused(f"the review cannot be prepared: {error}") from error
if len(notes) > NOTES_LIMIT:
raise Refused(f"the notes hold {len(notes)} characters, the hub takes at most {NOTES_LIMIT}")
arguments = {key: item[key] for key in ("repo", "worktree", "branch", "tree")}
arguments.update(title=args.title, page=str(args.page), notes=notes, gate=args.gate, score=args.score, agent=args.agent)
body = review_body({**arguments, "diff": diff, "sealed": sealed})
if len(body) > DIFF_BODY_LIMIT:
print(f"approval: the review goes without its diff, its {len(body)} bytes pass the hub's {DIFF_BODY_LIMIT}", file=sys.stderr)
body = review_body(arguments)
headers = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}
try:
answer = load(urllib.request.Request(f"{base_url(args.port)}/mcp", data=body, headers=headers, method="POST"), SLACK)
except (OSError, ValueError) as error:
raise Refused(f"the Agent Orchestrator gave no answer: {error}") from error
result = answer.get("result") if isinstance(answer, dict) else None
if not isinstance(result, dict) or result.get("isError") or not isinstance(result.get("structuredContent"), dict):
raise Refused(f"the Agent Orchestrator refused the review: {json.dumps(answer)[:500]}")
return json.dumps(result["structuredContent"])
def pin_credential(args: argparse.Namespace) -> str:
try:
credential = json.loads(b64decode(args.credential, "credential"))
except (ValueError, RecursionError) as error:
raise Refused("the credential blob is no JSON") from error
entry = attested(credential, origin_of(args.port))
entries = pin(args.approvers, entry, time.time())
return f"pinned {entry['id']} ({ALGORITHMS[entry['alg']]}) in {args.approvers}; {len(entries)} key(s) pinned"
def review_id(text: str) -> str:
if not ID.fullmatch(text):
raise argparse.ArgumentTypeError("a review id is 16 hex digits")
return text
def main() -> int:
parser = argparse.ArgumentParser(prog="approval")
commands = parser.add_subparsers(dest="command", required=True)
pinning = commands.add_parser("pin")
verifying = commands.add_parser("verify")
for sub in (pinning, verifying):
sub.add_argument("--port", type=int, required=True)
sub.add_argument("--approvers", type=Path, required=True)
pinning.add_argument("--credential", required=True)
verifying.add_argument("--replay", type=Path, required=True)
verifying.add_argument("--review", type=review_id, required=True)
verifying.add_argument("--gate", choices=("pass", "fail"), required=True)
verifying.add_argument("--record", type=Path)
requesting = commands.add_parser("request")
requesting.add_argument("--port", type=int, required=True)
for name in ("--title", "--score", "--agent"):
requesting.add_argument(name, required=True)
requesting.add_argument("--page", type=Path, required=True)
requesting.add_argument("--notes", type=Path, required=True)
requesting.add_argument("--gate", choices=("pass", "fail"), required=True)
requesting.add_argument("--rules", type=Path)
args = parser.parse_args()
run = {"pin": pin_credential, "verify": verify_commit, "request": request_review}[args.command]
try:
print(run(args))
except (Refused, OSError) as error:
print(f"refused: {error}", file=sys.stderr)
return 1
return 0
if __name__ == "__main__":
raise SystemExit(main())