Files
skills/orchestrator/client/permission_hook.py
T
Kevin Veen-BirkenbachandClaude Opus 5.5 9742884308 feat(orchestrator): firewall view with signed settings changes (001 S6)
Requirement 001 S6: the hub gets a Firewall view of the Claude Code permission and sandbox settings. The operator signs each change with the passkey; a host settings writer (systemd path unit) applies only exact, signed changes to allowlisted settings files through O_NOFOLLOW directory and file descriptors, and a timer refreshes the view. Every signed text and every page sink refuses or marks hidden characters: Cc, Cf, Zl, Zp, every space but U+0020 and the Default_Ignorable set, with U+FE0E/U+FE0F allowed only after one of the 359 non-ASCII emoji bases of Unicode 16 (shared table, validated at import, the same pair rule on the page). Removal of a deny, ask or denyRead entry is exempt only as an exact single remove. The permission hook prints the hub's refusal reason, cleaned of hidden characters. Accepted MEDUSA false positives (independent review, operator pick): 38 this round, mainly the Unicode defence tables read as attack patterns, generic MM-SCAN-058 heuristics, WEB-FLASK-004 at view.py:213 (ints from the validated table via tojson), EXF26-TOOL-004 on the non-secret WebAuthn challenge, PRIV-SCAN-060 on the office-action shape check and PQC007 on a picker key.

🎯 Fix: 95 %
💥 Break: 3 %
💸 Cost: –
⏱️ Time: –
🛡️ Security: 100 %
🏆 Score: 92
🚦 Gate: ✅ 90/5, cost and time <= 100, security 100 %

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 18:14:17 +00:00

228 lines
9.5 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 carries the diff
staged_diff.py builds of the tree its directory stages (of the
working tree against HEAD with -a or --all), content withheld per
the MEDUSA rules of the pipx install; none 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.
"""
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"
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) -> tuple[Path, bool] | None:
return staged_diff.commit_of(ask["command"], ask["cwd"]) if ask["tool"] == "Bash" and ask["cwd"] else 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},
{} 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:
return pinned, {"diff": staged_diff.bound_diff(*target, pinned, rules)}
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.
"""
if chosen != {"behavior": "allow"} or commit_target(ask) is None:
return chosen
try:
now = staged_diff.binding(*commit_target(ask))
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
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())