Files
skills/orchestrator/client/approval.py
T
Kevin Veen-BirkenbachandClaude Opus 5.5 af3555e88b feat(orchestrator): reveal withheld diff content under a passkey signature (019)
staged_diff masks only the secret rule hits and seals each masked file's clear patch apart; reviews and asks store the sealed patches next to their diff, delete them once the item leaves pending, and the hub sweeps orphans. POST /api/diffs/<kind>/<id>/reveal/sign and /reveal hand the clear patches to a signed request; page-diff.js offers Reveal per hidden file and Reveal all, keeps the clear text in the page only and forgets it once the item leaves the inbox. Requirement 019, unit, hub and e2e tests.

Accepted MEDUSA false positives (security.py accept after kvb-think-criticize, 2026-11-17): approval.py FTSCAN-231 WEB-SSRF RH005; permission_hook.py MM-SCAN-058 WEB-SSRF RH005; staged_diff.py SAST-ENV-001 AI-BACKDOOR-006 B603; hub.py MEX-SCAN-1167 INF-SCAN-589; page-load.js EXA002; hub_case.py TC001-TC009 INF-SCAN-2057/2206/2440/2457 EXA002 EXA006 PL002 B603 FTSC-SCAN-089.

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:04:35 +00:00

163 lines
7.6 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>: run in the worktree right before the commit;
fetches the review's signature from the Agent Orchestrator on 127.0.0.1:<port>
and 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 verify_commit(args: argparse.Namespace) -> str:
review = 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)
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())