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>
248 lines
10 KiB
Python
Executable File
248 lines
10 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
"""Args:
|
|
--port: port of the Agent Orchestrator on 127.0.0.1; the signature's origin is
|
|
http://localhost:<port>.
|
|
--timeout: seconds to wait for the operator's decision; keep it below the
|
|
hook's timeout in settings.json.
|
|
--approvers: the pinned passkeys, e.g. ~/.config/kvb-orchestrator/approvers.json.
|
|
--replay: this hook's replay store, outside the hub's reach, e.g.
|
|
~/.local/state/kvb-orchestrator-approvals/hook.json.
|
|
stdin: the Claude Code PermissionRequest hook input.
|
|
|
|
Returns:
|
|
stdout: the PermissionRequest decision JSON: allow only when a pinned
|
|
passkey signed exactly this tool, command, cwd, session and ask id;
|
|
deny when the operator denied in the Agent Orchestrator, with the
|
|
reason only when a pinned passkey signed it. Nothing on timeout,
|
|
error, a missing or invalid signature, a value longer than the hub
|
|
takes or a hub that is down, so Claude Code shows its own dialog.
|
|
The exit code is 0. An ask for a Bash git commit of exactly the
|
|
staged index (staged_diff.commit_of) carries the diff staged_diff.py
|
|
builds of the tree its directory stages, secrets masked per the
|
|
MEDUSA rules of the pipx install, and the sealed clear patches of
|
|
its masked files apart; neither when it cannot be built or the body
|
|
would pass DIFF_BODY_LIMIT. An allow of such an ask turns
|
|
into a deny with CHANGED when what the commit records
|
|
(staged_diff.binding) differs right before answering from the
|
|
preview's, and with UNBOUND when either cannot be read. Any other
|
|
Bash command that may run git commit (-a, --all, -i, -o, -p, a
|
|
pathspec, a chain, a wrapper) is not approvable: no ask reaches the
|
|
hub, stderr gets WORKTREE and Claude Code shows its own dialog.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import json
|
|
import sys
|
|
import time
|
|
import urllib.error
|
|
import urllib.request
|
|
from pathlib import Path
|
|
|
|
import hub_api
|
|
import hub_limits
|
|
import signing
|
|
import staged_diff
|
|
import verifier
|
|
|
|
POLL = 25.0
|
|
NAME_LIMIT = 200
|
|
COMMAND_LIMIT = 4000
|
|
PATH_LIMIT = hub_limits.PATH_LIMIT
|
|
LIMITS = {"tool": NAME_LIMIT, "command": COMMAND_LIMIT, "cwd": PATH_LIMIT, "session": NAME_LIMIT, "agent": NAME_LIMIT}
|
|
DENIED = "The operator denied this in the Agent Orchestrator."
|
|
CHANGED = "staged tree changed since the preview"
|
|
UNBOUND = "the staged tree cannot be read, so the allow is not bound to it"
|
|
WORKTREE = "commit reads the working tree; stage the files and commit the index"
|
|
ALLOW = {"behavior": "allow"}
|
|
REASON_LIMIT = 2000
|
|
FAILURES = (OSError, ValueError, staged_diff.DiffError)
|
|
|
|
|
|
def summary(tool_input: object) -> str:
|
|
if isinstance(tool_input, dict):
|
|
for key in ("command", "file_path", "url", "pattern", "path"):
|
|
if isinstance(tool_input.get(key), str):
|
|
return tool_input[key]
|
|
return json.dumps(tool_input, ensure_ascii=False)
|
|
|
|
|
|
def facts(hook: dict) -> dict:
|
|
return {
|
|
"tool": str(hook.get("tool_name") or "?"),
|
|
"command": summary(hook.get("tool_input")),
|
|
"cwd": str(hook.get("cwd") or ""),
|
|
"session": str(hook.get("session_id") or ""),
|
|
"agent": str(hook.get("agent_type") or ""),
|
|
}
|
|
|
|
|
|
def commit_target(ask: dict) -> Path | None:
|
|
return staged_diff.commit_of(ask["command"], ask["cwd"]) if ask["tool"] == "Bash" and ask["cwd"] else None
|
|
|
|
|
|
def unapprovable(ask: dict) -> bool:
|
|
return ask["tool"] == "Bash" and staged_diff.names_commit(ask["command"]) and commit_target(ask) is None
|
|
|
|
|
|
def commit_diff(ask: dict, rules: Path | None) -> tuple[str | None, dict]:
|
|
"""Returns:
|
|
For a commit ask, what the commit records (staged_diff.binding, None
|
|
when it cannot be read) and {"diff": the preview of exactly that,
|
|
"sealed": the clear patches of its masked files}, {} when it cannot
|
|
be built; None and {} for any other ask.
|
|
"""
|
|
target = commit_target(ask)
|
|
if target is None:
|
|
return None, {}
|
|
try:
|
|
pinned = staged_diff.binding(target)
|
|
except FAILURES as error:
|
|
print(f"kvb-orchestrator: the ask goes without its diff and an allow of it turns into a deny: {error}", file=sys.stderr)
|
|
return None, {}
|
|
try:
|
|
diff, sealed = staged_diff.bound_diff(target, pinned, rules)
|
|
return pinned, {"diff": diff, "sealed": sealed}
|
|
except FAILURES as error:
|
|
print(f"kvb-orchestrator: the ask goes without its diff: {error}", file=sys.stderr)
|
|
return pinned, {}
|
|
|
|
|
|
def clean(text: str) -> str:
|
|
"""Returns:
|
|
text on one line for the terminal and the agent: every character
|
|
signing.unseen() names, a C0 or C1 control, a bidi or zero-width
|
|
character among them, shown as ?, but a selector signing.presented()
|
|
accepts; cut at REASON_LIMIT.
|
|
"""
|
|
stripped = text.strip()
|
|
return "".join("?" if signing.unseen(char) and not signing.presented(stripped, index) else char for index, char in enumerate(stripped))[:REASON_LIMIT]
|
|
|
|
|
|
def refusal(error: urllib.error.HTTPError) -> str:
|
|
"""Returns:
|
|
The reason the hub sent with an error status, on one line, or the
|
|
status text when its body cannot be read.
|
|
"""
|
|
try:
|
|
body = error.read().decode("utf-8", "replace")
|
|
except OSError:
|
|
body = ""
|
|
return clean(body or str(error.reason))
|
|
|
|
|
|
def bound(chosen: dict | None, ask: dict, pinned: str | None) -> dict | None:
|
|
"""Args:
|
|
pinned: what the commit recorded when the ask was made, None when
|
|
that could not be read.
|
|
|
|
Returns:
|
|
chosen, or for an allow of a commit ask a deny with CHANGED when
|
|
what it records now differs from pinned, with UNBOUND and the error
|
|
when either cannot be read; None for an allow of an unapprovable ask.
|
|
"""
|
|
if chosen != ALLOW:
|
|
return chosen
|
|
if unapprovable(ask):
|
|
return None
|
|
target = commit_target(ask)
|
|
if target is None:
|
|
return chosen
|
|
try:
|
|
now = staged_diff.binding(target)
|
|
except FAILURES as error:
|
|
return {"behavior": "deny", "message": f"{UNBOUND}: {clean(str(error))}"}
|
|
if pinned is None:
|
|
return {"behavior": "deny", "message": UNBOUND}
|
|
return chosen if now == pinned else {"behavior": "deny", "message": CHANGED}
|
|
|
|
|
|
def encoded(payload: dict) -> bytes:
|
|
return json.dumps(payload).encode()
|
|
|
|
|
|
def create(base: str, ask: dict, timeout: float, shown: dict) -> str:
|
|
data = encoded({**ask, "timeout": timeout, **shown})
|
|
if len(data) > hub_limits.DIFF_BODY_LIMIT:
|
|
print(f"kvb-orchestrator: the ask goes without its diff, its {len(data)} bytes pass the hub's {hub_limits.DIFF_BODY_LIMIT}", file=sys.stderr)
|
|
data = encoded({**ask, "timeout": timeout})
|
|
headers = {"Content-Type": "application/json", **hub_api.GUARD}
|
|
request = urllib.request.Request(f"{base}/api/asks", data=data, headers=headers, method="POST")
|
|
ask_id = hub_api.call(request, hub_api.SLACK)["id"]
|
|
if not isinstance(ask_id, str) or not signing.ID.fullmatch(ask_id):
|
|
raise ValueError("the hub answered no ask id")
|
|
return ask_id
|
|
|
|
|
|
def status(base: str, ask_id: str, wait: float) -> dict:
|
|
answer = hub_api.call(urllib.request.Request(f"{base}/api/asks/{ask_id}?wait={wait:.1f}"), wait + hub_api.SLACK)
|
|
if not isinstance(answer.get("status"), str):
|
|
raise TypeError("the hub answered no status")
|
|
return answer
|
|
|
|
|
|
def denied(answer: dict, item: dict, trust: verifier.Trust) -> str:
|
|
reason, channel, to = answer.get("reason"), answer.get("channel"), answer.get("to")
|
|
if not all(isinstance(value, str) for value in (reason, channel, to)) or not reason.strip():
|
|
return DENIED
|
|
try:
|
|
verifier.check(answer.get("proof"), signing.denial_item(item, channel, reason, to), "", trust, time.time())
|
|
except (signing.Refused, OSError) as error:
|
|
print(f"kvb-orchestrator: the reason is not signed, the agent gets the denial without it: {error}", file=sys.stderr)
|
|
return DENIED
|
|
return f"{DENIED} Reason: {clean(reason)}"
|
|
|
|
|
|
def decision(answer: dict, item: dict, trust: verifier.Trust) -> dict | None:
|
|
if answer["status"] == "denied":
|
|
return {"behavior": "deny", "message": denied(answer, item, trust)}
|
|
if answer["status"] != "allowed":
|
|
return None
|
|
try:
|
|
verifier.check(answer.get("proof"), item, "", trust, time.time())
|
|
except (signing.Refused, OSError) as error:
|
|
print(f"kvb-orchestrator: not signed, Claude Code asks instead: {error}", file=sys.stderr)
|
|
return None
|
|
return {"behavior": "allow"}
|
|
|
|
|
|
def main() -> int:
|
|
parser = argparse.ArgumentParser(prog="permission_hook")
|
|
parser.add_argument("--port", type=int, required=True)
|
|
parser.add_argument("--timeout", type=float, required=True)
|
|
parser.add_argument("--approvers", type=Path, required=True)
|
|
parser.add_argument("--replay", type=Path, required=True)
|
|
args = parser.parse_args()
|
|
base = hub_api.base_url(args.port)
|
|
trust = verifier.Trust(approvers=args.approvers, replay=args.replay, origin=signing.origin_of(args.port))
|
|
deadline = time.monotonic() + args.timeout
|
|
try:
|
|
hook = json.load(sys.stdin)
|
|
ask = facts(hook)
|
|
too_long = [name for name, limit in LIMITS.items() if len(ask[name]) > limit]
|
|
if too_long:
|
|
print(f"kvb-orchestrator: {', '.join(too_long)} too long to sign in full, Claude Code asks instead", file=sys.stderr)
|
|
return 0
|
|
if unapprovable(ask):
|
|
print(f"kvb-orchestrator: {WORKTREE}", file=sys.stderr)
|
|
return 0
|
|
pinned, shown = commit_diff(ask, staged_diff.rules_root())
|
|
ask_id = create(base, ask, args.timeout, shown)
|
|
answer = {"status": "pending"}
|
|
while answer["status"] == "pending" and (left := deadline - time.monotonic()) > 0:
|
|
answer = status(base, ask_id, min(left, POLL))
|
|
except urllib.error.HTTPError as error:
|
|
print(f"kvb-orchestrator: the hub answered {error.code}, Claude Code asks instead: {refusal(error)}", file=sys.stderr)
|
|
return 0
|
|
except (OSError, ValueError, KeyError, TypeError, AttributeError):
|
|
return 0
|
|
chosen = bound(decision(answer, signing.ask_item(ask_id, ask["tool"], ask["command"], ask["cwd"], ask["session"]), trust), ask, pinned)
|
|
if chosen is not None:
|
|
print(json.dumps({"hookSpecificOutput": {"hookEventName": "PermissionRequest", "decision": chosen}}))
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|