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>
281 lines
11 KiB
Python
Executable File
281 lines
11 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
"""Args:
|
|
--port: port of the Agent Orchestrator; the signature's origin is
|
|
http://localhost:<port>.
|
|
--jobs: the directory the hub writes signed office orders into, e.g.
|
|
~/.local/state/kvb-orchestrator/offices/jobs.
|
|
--results: the directory each job's result goes to as <id>.json.
|
|
--approvers: the pinned passkeys, e.g. ~/.config/kvb-orchestrator/approvers.json.
|
|
--replay: this runner's replay store, outside the hub's reach, e.g.
|
|
~/.local/state/kvb-orchestrator-approvals/offices.json.
|
|
--council: the council directory every agent shares, e.g.
|
|
/tmp/agents-council.
|
|
--script: the installed council.py of the kvb-org-organize skill.
|
|
|
|
Returns:
|
|
Runs once over every job in --jobs, as the operator on the host: per item
|
|
it verifies the operator's passkey signature over action, office, holder,
|
|
session and work, refuses a council directory others can write and an
|
|
office path holding a link, and checks that the office still has the
|
|
signed holder. A takeover or recall then moves the office aside, reads its
|
|
claim there and removes it only while that claim names the signed holder,
|
|
else it puts the office back; an appoint or takeover ends in a plain
|
|
council.py claim for the successor, run as an argument list, never through
|
|
a shell: a live Claude Code successor goes in as CLAUDE_CODE_SESSION_ID,
|
|
any other as --session. Writes each item's result and removes the job.
|
|
The exit code is 0.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import json
|
|
import os
|
|
import re
|
|
import shutil
|
|
import stat
|
|
import subprocess
|
|
import sys
|
|
import time
|
|
from pathlib import Path
|
|
|
|
import signing
|
|
import verifier
|
|
|
|
JOB = re.compile(r"[0-9a-f]{16}\.json")
|
|
SAFE_PATH = "/usr/local/bin:/usr/bin:/bin"
|
|
CLAIM = "claim.json"
|
|
CLAIM_SHAPE = (("session", str), ("runtime", str), ("beat", (int, float)))
|
|
DIRECTORY = verifier.FOLDER
|
|
OUTPUT_LIMIT = 4000
|
|
TIMEOUT = 120
|
|
|
|
|
|
def claim_in(office_fd: int) -> dict | None:
|
|
"""Returns:
|
|
The claim of the open office directory in the shape council.py
|
|
reads, or None.
|
|
"""
|
|
try:
|
|
claim = json.loads(verifier.read_regular(CLAIM, office_fd))
|
|
except (OSError, ValueError, RecursionError):
|
|
return None
|
|
shaped = isinstance(claim, dict) and all(isinstance(claim.get(key), kind) for key, kind in CLAIM_SHAPE)
|
|
return claim if shaped else None
|
|
|
|
|
|
def parent_of(council: Path, office: str) -> tuple[int, str]:
|
|
"""Returns:
|
|
The open directory holding the office, without following a link on
|
|
the way, and the office's last name; the caller closes it.
|
|
"""
|
|
*dirs, name = office.split("/")
|
|
fd = os.open(council, DIRECTORY)
|
|
try:
|
|
for part in dirs:
|
|
child = os.open(part, DIRECTORY, dir_fd=fd)
|
|
os.close(fd)
|
|
fd = child
|
|
except BaseException:
|
|
os.close(fd)
|
|
raise
|
|
return fd, name
|
|
|
|
|
|
def unsafe(council: Path, office: str) -> str | None:
|
|
"""Returns:
|
|
Why the council directory or the office's path below it must not be
|
|
used, or None.
|
|
"""
|
|
try:
|
|
root = council.lstat()
|
|
except OSError as error:
|
|
return f"the council directory is unreadable: {error.strerror}"
|
|
if not stat.S_ISDIR(root.st_mode) or root.st_uid != os.getuid() or root.st_mode & 0o022:
|
|
return f"{council} is no directory of uid {os.getuid()}, or others can write it"
|
|
path = council
|
|
for part in office.split("/"):
|
|
path = path / part
|
|
try:
|
|
found = path.lstat()
|
|
except FileNotFoundError:
|
|
return None
|
|
if not stat.S_ISDIR(found.st_mode):
|
|
return f"{path} is a link or no directory"
|
|
try:
|
|
found = (path / CLAIM).lstat()
|
|
except FileNotFoundError:
|
|
return None
|
|
return None if stat.S_ISREG(found.st_mode) else f"{path / CLAIM} is a link or no file"
|
|
|
|
|
|
def holder_of(council: Path, office: str) -> str | None:
|
|
"""Returns:
|
|
The session holding the office, empty while it is vacant, None while
|
|
its claim is missing, unreadable or not in the shape council.py reads.
|
|
"""
|
|
try:
|
|
parent, name = parent_of(council, office)
|
|
except FileNotFoundError:
|
|
return ""
|
|
except OSError:
|
|
return None
|
|
try:
|
|
fd = os.open(name, DIRECTORY, dir_fd=parent)
|
|
except FileNotFoundError:
|
|
return ""
|
|
except OSError:
|
|
return None
|
|
finally:
|
|
os.close(parent)
|
|
try:
|
|
claim = claim_in(fd)
|
|
finally:
|
|
os.close(fd)
|
|
return claim["session"] if claim else None
|
|
|
|
|
|
def vacate(council: Path, office: str, holder: str) -> str | None:
|
|
"""Args:
|
|
council: the council directory.
|
|
office: the office to empty.
|
|
holder: the session the operator signed as its holder.
|
|
|
|
Returns:
|
|
None once the office is gone, else why nothing changed.
|
|
"""
|
|
parent, name = parent_of(council, office)
|
|
try:
|
|
tomb = f"{name}.recalled-{os.getpid()}-{time.time_ns()}"
|
|
try:
|
|
os.rename(name, tomb, src_dir_fd=parent, dst_dir_fd=parent)
|
|
except FileNotFoundError:
|
|
return f"the holder changed since the signature: signed {holder}, now vacant; nothing changed"
|
|
try:
|
|
fd = os.open(tomb, DIRECTORY, dir_fd=parent)
|
|
except OSError:
|
|
claim = None
|
|
else:
|
|
try:
|
|
claim = claim_in(fd)
|
|
finally:
|
|
os.close(fd)
|
|
if claim is not None and claim["session"] == holder:
|
|
shutil.rmtree(tomb, dir_fd=parent)
|
|
return None
|
|
now_held = "unreadable" if claim is None else claim["session"]
|
|
try:
|
|
os.lstat(name, dir_fd=parent)
|
|
except FileNotFoundError:
|
|
# Python has no RENAME_NOREPLACE: rename(2) replaces an empty office a claimant made after the lstat.
|
|
os.rename(tomb, name, src_dir_fd=parent, dst_dir_fd=parent)
|
|
return f"the holder changed since the signature: signed {holder}, now {now_held}; nothing changed"
|
|
kept = council.joinpath(*office.split("/")[:-1], tomb)
|
|
return f"the holder changed since the signature: signed {holder}, now {now_held}; a new claim arrived meanwhile, the old office waits at {kept}"
|
|
finally:
|
|
os.close(parent)
|
|
|
|
|
|
def live(home: Path, session: str) -> bool:
|
|
for path in (home / ".claude" / "sessions").glob("*.json"):
|
|
try:
|
|
data = json.loads(path.read_text(encoding="utf-8"))
|
|
except (OSError, ValueError):
|
|
continue
|
|
if isinstance(data, dict) and data.get("sessionId") == session:
|
|
return True
|
|
return False
|
|
|
|
|
|
class Offices:
|
|
def __init__(self, trust: verifier.Trust, council: Path, script: Path, home: Path) -> None:
|
|
self.trust = trust
|
|
self.council = council
|
|
self.script = script
|
|
self.home = home
|
|
|
|
def command(self, item: dict) -> tuple[list[str], dict[str, str]]:
|
|
argv = [sys.executable, "-I", "-B", str(self.script), "claim", item["office"], f"--work={item['work']}"]
|
|
env = {"PATH": SAFE_PATH, "HOME": str(self.home), "AGENTS_COUNCIL_ROOT": str(self.council)}
|
|
if live(self.home, item["session"]):
|
|
return argv, {**env, "CLAUDE_CODE_SESSION_ID": item["session"]}
|
|
return [*argv, f"--session={item['session']}"], env
|
|
|
|
def item(self, item: dict, proof: object, now: float) -> dict:
|
|
"""Args:
|
|
item: one well-formed office order.
|
|
proof: the job's {"payload", "assertion"}.
|
|
now: the current time in epoch seconds.
|
|
|
|
Returns:
|
|
The order with status done, failed or refused, the reason, the
|
|
exit code and the output of council.py; a refused order changed
|
|
nothing.
|
|
"""
|
|
def ended(status: str, reason: str, code: int | None, output: str) -> dict:
|
|
return {**item, "status": status, "reason": reason, "code": code, "output": output}
|
|
|
|
try:
|
|
verifier.check(proof, signing.office_item(**item), "", self.trust, now)
|
|
except (signing.Refused, OSError) as error:
|
|
return ended("refused", f"no valid operator signature: {error}", None, "")
|
|
reason = unsafe(self.council, item["office"])
|
|
if reason:
|
|
return ended("refused", reason, None, "")
|
|
current = holder_of(self.council, item["office"])
|
|
if current != item["holder"]:
|
|
now_held = "unreadable" if current is None else current or "vacant"
|
|
return ended("refused", f"the holder changed since the signature: signed {item['holder'] or 'vacant'}, now {now_held}", None, "")
|
|
if item["action"] != "appoint":
|
|
try:
|
|
reason = vacate(self.council, item["office"], item["holder"])
|
|
except OSError as error:
|
|
return ended("failed", f"the office could not be emptied: {error.strerror or error}; nothing changed", None, "")
|
|
if reason:
|
|
return ended("refused", reason, None, "")
|
|
if item["action"] == "recall":
|
|
return ended("done", "", None, f"recalled {item['office']} from {item['holder']}")
|
|
argv, env = self.command(item)
|
|
try:
|
|
done = subprocess.run(argv, cwd="/", env=env, stdin=subprocess.DEVNULL, capture_output=True, text=True, errors="replace", timeout=TIMEOUT, check=False)
|
|
except (OSError, subprocess.TimeoutExpired) as error:
|
|
return ended("failed", f"{error}; the office is vacant now", 127, "")
|
|
output = (done.stdout + done.stderr)[-OUTPUT_LIMIT:]
|
|
if done.returncode == 0:
|
|
return ended("done", "", 0, output)
|
|
vacant = "; the office is vacant now" if item["action"] == "takeover" else ""
|
|
return ended("failed", f"{output.strip()[-500:]}{vacant}", done.returncode, output)
|
|
|
|
def job(self, folder: int, path: Path, now: float) -> dict:
|
|
try:
|
|
job = json.loads(verifier.read_regular(path, folder))
|
|
except (OSError, ValueError, RecursionError) as error:
|
|
return {"id": path.stem, "finished": now, "items": [], "error": f"unreadable job: {error}"}
|
|
items = job.get("items") if isinstance(job, dict) else None
|
|
if not isinstance(items, list) or not items or any(signing.office_problem(item) for item in items) or job.get("id") != path.stem:
|
|
return {"id": path.stem, "finished": now, "items": [], "error": "malformed job: refused, nothing changed"}
|
|
results = [self.item(item, job.get("proof"), now) for item in items]
|
|
return {"id": path.stem, "finished": time.time(), "items": results}
|
|
|
|
|
|
def cycle(jobs: Path, results: Path, offices: Offices) -> int:
|
|
def run(folder: int, name: str) -> dict | None:
|
|
return offices.job(folder, Path(name), time.time()) if JOB.fullmatch(name) else None
|
|
|
|
return verifier.drain(jobs, results, run)
|
|
|
|
|
|
def main() -> int:
|
|
parser = argparse.ArgumentParser(prog="offices")
|
|
parser.add_argument("--port", type=int, required=True)
|
|
for name in ("--jobs", "--results", "--approvers", "--replay", "--council", "--script"):
|
|
parser.add_argument(name, type=Path, required=True)
|
|
args = parser.parse_args()
|
|
trust = verifier.Trust(approvers=args.approvers, replay=args.replay, origin=signing.origin_of(args.port))
|
|
cycle(args.jobs, args.results, Offices(trust, args.council, args.script, Path.home()))
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|