Merge branch 'feature/orchestrator-firewall' into unify/skills-20261112-night

# Conflicts:
#	orchestrator/Dockerfile
#	orchestrator/kvb_orchestrator/view.py
#	orchestrator/templates/index.html.j2
#	orchestrator/templates/page-cleanup.js
#	scripts/orchestrator.sh
This commit is contained in:
Kevin Veen-Birkenbach committed 2026-11-13 18:18:54 +00:00
commit d364cfe55f
48 files changed
+3438 -106

No files matched your search

+1 -1
View File
@@ -80,7 +80,7 @@ def tree_facts(tree: Path) -> tuple[dict[str, str], bool]:
data = json.loads(tree.read_text(encoding="utf-8"))
known = {entry["path"]: entry.get("default") if isinstance(entry.get("default"), str) else "" for entry in data["repos"] if entry.get("known") is True and isinstance(entry.get("path"), str)}
return known, data.get("delete_ready") is True
except (OSError, ValueError, KeyError, TypeError, AttributeError):
except Exception: # noqa: BLE001
return {}, False
+24
View File
@@ -0,0 +1,24 @@
{
"source": "https://www.unicode.org/Public/16.0.0/ucd/emoji/emoji-variation-sequences.txt",
"unicode": "16.0.0",
"bases": [
"00A9", "00AE", "203C", "2049", "2122", "2139", "2194", "2195", "2196", "2197", "2198", "2199", "21A9", "21AA", "231A", "231B", "2328", "23CF", "23E9", "23EA",
"23EB", "23EC", "23ED", "23EE", "23EF", "23F0", "23F1", "23F2", "23F3", "23F8", "23F9", "23FA", "24C2", "25AA", "25AB", "25B6", "25C0", "25FB", "25FC", "25FD",
"25FE", "2600", "2601", "2602", "2603", "2604", "260E", "2611", "2614", "2615", "2618", "261D", "2620", "2622", "2623", "2626", "262A", "262E", "262F", "2638",
"2639", "263A", "2640", "2642", "2648", "2649", "264A", "264B", "264C", "264D", "264E", "264F", "2650", "2651", "2652", "2653", "265F", "2660", "2663", "2665",
"2666", "2668", "267B", "267E", "267F", "2692", "2693", "2694", "2695", "2696", "2697", "2699", "269B", "269C", "26A0", "26A1", "26A7", "26AA", "26AB", "26B0",
"26B1", "26BD", "26BE", "26C4", "26C5", "26C8", "26CE", "26CF", "26D1", "26D3", "26D4", "26E9", "26EA", "26F0", "26F1", "26F2", "26F3", "26F4", "26F5", "26F7",
"26F8", "26F9", "26FA", "26FD", "2702", "2705", "2708", "2709", "270A", "270B", "270C", "270D", "270F", "2712", "2714", "2716", "271D", "2721", "2728", "2733",
"2734", "2744", "2747", "274C", "274E", "2753", "2754", "2755", "2757", "2763", "2764", "2795", "2796", "2797", "27A1", "27B0", "27BF", "2934", "2935", "2B05",
"2B06", "2B07", "2B1B", "2B1C", "2B50", "2B55", "3030", "303D", "3297", "3299", "1F004", "1F170", "1F171", "1F17E", "1F17F", "1F202", "1F21A", "1F22F", "1F237", "1F30D",
"1F30E", "1F30F", "1F315", "1F31C", "1F321", "1F324", "1F325", "1F326", "1F327", "1F328", "1F329", "1F32A", "1F32B", "1F32C", "1F336", "1F378", "1F37D", "1F393", "1F396", "1F397",
"1F399", "1F39A", "1F39B", "1F39E", "1F39F", "1F3A7", "1F3AC", "1F3AD", "1F3AE", "1F3C2", "1F3C4", "1F3C6", "1F3CA", "1F3CB", "1F3CC", "1F3CD", "1F3CE", "1F3D4", "1F3D5", "1F3D6",
"1F3D7", "1F3D8", "1F3D9", "1F3DA", "1F3DB", "1F3DC", "1F3DD", "1F3DE", "1F3DF", "1F3E0", "1F3ED", "1F3F3", "1F3F5", "1F3F7", "1F408", "1F415", "1F41F", "1F426", "1F43F", "1F441",
"1F442", "1F446", "1F447", "1F448", "1F449", "1F44D", "1F44E", "1F453", "1F46A", "1F47D", "1F4A3", "1F4B0", "1F4B3", "1F4BB", "1F4BF", "1F4CB", "1F4DA", "1F4DF", "1F4E4", "1F4E5",
"1F4E6", "1F4EA", "1F4EB", "1F4EC", "1F4ED", "1F4F7", "1F4F9", "1F4FA", "1F4FB", "1F4FD", "1F508", "1F50D", "1F512", "1F513", "1F549", "1F54A", "1F550", "1F551", "1F552", "1F553",
"1F554", "1F555", "1F556", "1F557", "1F558", "1F559", "1F55A", "1F55B", "1F55C", "1F55D", "1F55E", "1F55F", "1F560", "1F561", "1F562", "1F563", "1F564", "1F565", "1F566", "1F567",
"1F56F", "1F570", "1F573", "1F574", "1F575", "1F576", "1F577", "1F578", "1F579", "1F587", "1F58A", "1F58B", "1F58C", "1F58D", "1F590", "1F5A5", "1F5A8", "1F5B1", "1F5B2", "1F5BC",
"1F5C2", "1F5C3", "1F5C4", "1F5D1", "1F5D2", "1F5D3", "1F5DC", "1F5DD", "1F5DE", "1F5E1", "1F5E3", "1F5E8", "1F5EF", "1F5F3", "1F5FA", "1F610", "1F687", "1F68D", "1F691", "1F694",
"1F698", "1F6AD", "1F6B2", "1F6B9", "1F6BA", "1F6BC", "1F6CB", "1F6CD", "1F6CE", "1F6CF", "1F6E0", "1F6E1", "1F6E2", "1F6E3", "1F6E4", "1F6E5", "1F6E9", "1F6F0", "1F6F3"
]
}
+24 -3
View File
@@ -30,9 +30,9 @@ from __future__ import annotations
import argparse
import json
import re
import sys
import time
import urllib.error
import urllib.request
from pathlib import Path
@@ -51,7 +51,6 @@ 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
CONTROL = re.compile(r"[\x00-\x1f\x7f]")
FAILURES = (OSError, ValueError, staged_diff.DiffError)
@@ -99,7 +98,26 @@ def commit_diff(ask: dict, rules: Path | None) -> tuple[str | None, dict]:
def clean(text: str) -> str:
return CONTROL.sub("?", text.strip())[:REASON_LIMIT]
"""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:
@@ -194,6 +212,9 @@ def main() -> int:
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)
+365
View File
@@ -0,0 +1,365 @@
#!/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 settings changes into, e.g.
~/.local/state/kvb-orchestrator/firewall/jobs.
--results: the directory each job's result goes to as <id>.json.
--view: the file the Firewall reads, e.g.
~/.local/state/kvb-orchestrator/firewall/view.json: per listed file
its path, sha256 and only its permissions and sandbox sections.
--approvers: the pinned passkeys, e.g. ~/.config/kvb-orchestrator/approvers.json.
--replay: this writer's replay store, outside the hub's reach, e.g.
~/.local/state/kvb-orchestrator-approvals/firewall.json.
--tree: the tree file `pkgmgr branch tree` writes; the repositories it
knows name the project settings files.
Returns:
Exit code 2 without touching anything when CLAUDECODE or
SANDBOX_RUNTIME is set: it runs only from its unit, never inside an
agent or its sandbox. Else, as the operator on the host, per item of
every job in --jobs: verifies the operator's passkey signature over
file, base and changes with the replay store; refuses a file outside the
fixed list (~/.claude/settings.json and <repository>/.claude/settings.json
of every repository the tree file knows), a link or non-directory on its
path, a file of another uid, a non-regular file and a file whose sha256
is no longer the signed base; then applies exactly the signed changes to
the parsed file, keeps every other key, copies the old bytes to
<file>.before-firewall-<job id> beside it and replaces the file
atomically, both with the file's mode (0600 for a new file). A refused
item changes nothing; a failed one keeps the file's content. Writes each
job's result, removes the job and rewrites --view, all through
verifier.drain() and verifier.private_dir(): relative to open directory
descriptors, never through a link, a linked or foreign jobs, results or
view directory refused with one line on stderr. The exit code is 0.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import math
import os
import secrets
import stat
import sys
import time
from pathlib import Path
import signing
import verifier
from cleanup import tree_facts
from offices import cycle
AGENT_MARKERS = ("CLAUDECODE", "SANDBOX_RUNTIME")
DIRECTORY = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC
FILE = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC
CREATE = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC
READ_LIMIT = 1 << 20
NEW_MODE = 0o600
BACKUP = "before-firewall"
OUTSIDE = "an agent or its sandbox runs this: the settings writer runs only from the kvb-orchestrator-firewall unit"
MISSING_DIRECTORY = "no directory: create it first"
def listed(home: Path, tree: Path) -> list[str]:
"""Returns:
The fixed list of settings files: the operator's own and those of
every repository the tree file knows.
"""
own = str(home / ".claude" / "settings.json")
projects = sorted(f"{repository.rstrip('/')}{signing.SETTINGS_FILE}" for repository in tree_facts(tree)[0])
return [own, *(path for path in projects if path != own)]
def parent_of(path: str) -> int:
"""Returns:
The open directory holding path, reached from / without following a
link on the way; the caller closes it.
"""
fd = os.open("/", DIRECTORY)
try:
for part in Path(path).parent.parts[1:]:
child = os.open(part, DIRECTORY, dir_fd=fd)
os.close(fd)
fd = child
except BaseException:
os.close(fd)
raise
return fd
def read_settings(parent: int, name: str) -> tuple[bytes | None, os.stat_result | None]:
"""Returns:
The file's bytes and status, None and None while it is missing.
Raises:
signing.Refused for a link, a non-regular file or one over
READ_LIMIT bytes.
"""
try:
fd = os.open(name, FILE, dir_fd=parent)
except FileNotFoundError:
return None, None
except OSError as error:
raise signing.Refused(f"the file opens only through a link or not at all: {error.strerror}") from None
with open(fd, "rb") as handle:
found = os.fstat(fd)
if not stat.S_ISREG(found.st_mode):
raise signing.Refused("the file is no regular file")
data = handle.read(READ_LIMIT + 1)
if len(data) > READ_LIMIT:
raise signing.Refused(f"the file is larger than {READ_LIMIT} bytes")
return data, found
def write_beside(parent: int, name: str, data: bytes, mode: int) -> str:
"""Args:
parent: the open directory.
name: the file to replace or create in it.
data: its new bytes.
mode: its permission bits.
Returns:
"" once the directory is synced, else why its sync failed after the
file was already replaced.
"""
temporary = f".{name}.{secrets.token_hex(8)}"
fd = os.open(temporary, CREATE, mode, dir_fd=parent)
try:
with open(fd, "wb") as handle:
os.fchmod(fd, mode)
handle.write(data)
handle.flush()
os.fsync(fd)
os.replace(temporary, name, src_dir_fd=parent, dst_dir_fd=parent)
except BaseException:
os.unlink(temporary, dir_fd=parent)
raise
try:
os.fsync(parent)
except OSError as error:
return error.strerror or type(error).__name__
return ""
class Unsafe(ValueError):
pass
def no_constant(name: str) -> float:
raise Unsafe(f"the file holds {name}, which JSON readers reject")
def finite(text: str) -> float:
value = float(text)
if not math.isfinite(value):
raise Unsafe("the file holds a number beyond the double range, which JSON readers reject")
return value
def unique(pairs: list[tuple[str, object]]) -> dict:
found = dict(pairs)
if len(found) != len(pairs):
raise Unsafe("the file repeats a key in one object")
return found
def parsed(data: bytes | None) -> dict:
"""Returns:
The settings object, {} while the file is missing.
Raises:
Unsafe for anything but strict JSON every reader parses alike: no
NaN, Infinity or overflowing number, no repeated key, no lone
surrogate, at most signing.DEPTH_LIMIT levels, an object at the top.
The reason never quotes the file.
"""
if data is None:
return {}
try:
settings = json.loads(data.decode("utf-8"), parse_constant=no_constant, parse_float=finite, object_pairs_hook=unique)
except Unsafe:
raise
except (ValueError, RecursionError) as error:
raise Unsafe(f"the file holds no strict JSON: {type(error).__name__}") from None
problem = signing.plain_problem(settings, 0) if isinstance(settings, dict) else "the file holds no JSON object"
if problem:
raise Unsafe(problem)
return settings
def digest(data: bytes | None) -> str:
return "" if data is None else hashlib.sha256(data).hexdigest()
def view_of(path: str) -> dict:
"""Returns:
{"path", "exists", "sha256", "error", "settings"}: settings only the
permissions and sandbox sections; error why the file was unreadable,
for anything unforeseen only the exception's class, so one bad path
never keeps the others or the view from being written.
"""
entry = {"path": path, "exists": False, "sha256": "", "error": "", "settings": {}}
try:
return read_view(path, entry)
except Exception as error: # noqa: BLE001
return {**entry, "error": f"unreadable: {type(error).__name__}"}
def read_view(path: str, entry: dict) -> dict:
try:
parent = parent_of(path)
except FileNotFoundError:
return {**entry, "error": MISSING_DIRECTORY}
except OSError as error:
return {**entry, "error": f"a link or no directory on the path: {error.strerror}"}
try:
data, _ = read_settings(parent, Path(path).name)
return {**entry, "exists": data is not None, "sha256": digest(data), "settings": signing.settings_view(parsed(data))}
except (OSError, Unsafe, signing.Refused) as error:
return {**entry, "error": str(error)[:300]}
finally:
os.close(parent)
class Writer:
def __init__(self, trust: verifier.Trust, home: Path, tree: Path) -> None:
self.trust = trust
self.home = home
self.tree = tree
def view(self) -> dict:
return {"written": time.time(), "files": [view_of(path) for path in listed(self.home, self.tree)]}
def apply(self, item: dict, job_id: str) -> dict:
"""Args:
item: one signed, well-formed settings change.
job_id: the job's id, part of the backup's name.
Returns:
{"backup", "sha256", "unsynced"}: the backup beside the file, ""
for a file that was missing, the new content's sha256, and why
the directory sync failed after a replace, "" when it did not.
Raises:
signing.Refused or OSError when nothing was written.
"""
name = Path(item["file"]).name
try:
parent = parent_of(item["file"])
except OSError as error:
raise signing.Refused(f"a link or no directory on the path: {error.strerror}") from None
try:
data, found = read_settings(parent, name)
if found is not None and found.st_uid != os.getuid():
raise signing.Refused(f"the file belongs to uid {found.st_uid}, not {os.getuid()}")
if digest(data) != item["base"]:
raise signing.Refused("the file changed since the signature")
text = (json.dumps(signing.apply_changes(parsed(data), item["changes"]), indent=2, ensure_ascii=False, allow_nan=False) + "\n").encode("utf-8")
mode = NEW_MODE if found is None else stat.S_IMODE(found.st_mode)
backup = unsynced = ""
if data is not None:
backup = f"{name}.{BACKUP}-{job_id}"
unsynced = write_beside(parent, backup, data, mode)
unsynced = write_beside(parent, name, text, mode) or unsynced
finally:
os.close(parent)
return {"backup": str(Path(item["file"]).with_name(backup)) if backup else "", "sha256": digest(text), "unsynced": unsynced}
def item(self, item: dict, proof: object, job_id: str, now: float) -> dict:
"""Args:
item: one well-formed settings change.
proof: the job's {"payload", "assertion"}.
job_id: the job's id.
now: the current time in epoch seconds.
Returns:
The item with status done, refused or failed and the reason; a
refused or failed item wrote nothing, and a failure's reason names
only its kind, never the file's content.
"""
try:
status, reason, written = self.outcome(item, proof, job_id, now)
except OSError as error:
status, reason, written = "failed", f"{error.strerror or error}; the file kept its content", {}
except Exception as error: # noqa: BLE001
status, reason, written = "failed", f"{error if isinstance(error, Unsafe) else type(error).__name__}; the file kept its content", {}
return {**item, "status": status, "reason": reason, **written}
def outcome(self, item: dict, proof: object, job_id: str, now: float) -> tuple[str, str, dict]:
try:
verifier.check(proof, signing.settings_item(item["file"], item["base"], item["changes"]), "", self.trust, now)
except (signing.Refused, OSError) as error:
return "refused", f"no valid operator signature: {error}", {}
if item["file"] not in listed(self.home, self.tree):
return "refused", "unlisted file: only ~/.claude/settings.json and the .claude/settings.json of a repository pkgmgr knows", {}
try:
written = self.apply(item, job_id)
except signing.Refused as error:
return "refused", str(error)[:500], {}
unsynced = written.pop("unsynced")
return "done", f"written, but its directory sync failed: {unsynced}; the change may not survive a crash" if unsynced else "", written
def job(self, folder: int, path: Path, now: float) -> dict:
"""Args:
folder: the open jobs directory, as verifier.drain() passes it.
path: the job's name in it.
now: the current time in epoch seconds.
Returns:
The job's result; whatever goes wrong in one job fails only that
job, so the next job and the view still run.
"""
try:
return self.checked_job(folder, path, now)
except Exception as error: # noqa: BLE001
return {"id": path.stem, "finished": now, "items": [], "error": f"failed: {type(error).__name__}; nothing changed"}
def checked_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.settings_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"}
return {"id": path.stem, "finished": time.time(), "items": [self.item(item, job.get("proof"), path.stem, now) for item in items]}
def main() -> int:
if any(marker in os.environ for marker in AGENT_MARKERS):
print(f"settings_writer: refused: {OUTSIDE}", file=sys.stderr)
return 2
parser = argparse.ArgumentParser(prog="settings_writer")
parser.add_argument("--port", type=int, required=True)
for name in ("--jobs", "--results", "--view", "--approvers", "--replay", "--tree"):
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))
writer = Writer(trust, Path.home(), args.tree)
try:
cycle(args.jobs, args.results, writer)
finally:
write_view(args.view, writer.view())
return 0
def write_view(path: Path, view: dict) -> None:
"""Args:
path: the view file, written relative to its directory opened by
verifier.private_dir(); a linked or foreign spool, or a write
that fails, prints one line and raises nothing, so an error of
the cycle before it still surfaces.
view: Writer.view().
"""
try:
with verifier.private_dir(path.parent, True) as folder:
verifier.write_at(folder, path.name, view)
except (signing.Refused, OSError) as error:
print(f"view not written: {error}", file=sys.stderr)
if __name__ == "__main__":
raise SystemExit(main())
+307 -1
View File
@@ -1,10 +1,12 @@
from __future__ import annotations
import base64
import copy
import fnmatch
import hashlib
import json
import re
import unicodedata
from pathlib import Path
RP_ID = "localhost"
@@ -35,6 +37,28 @@ GATE_BRANCH = re.compile(r"(?![-/])(?!.*\.\.)(?!.*@\{)(?!.*//)[^\x00-\x20\x7f~^:
TOKEN_FREE_MERGE = "ancestor"
APPROVAL_KEYS = {"v", "kind", "items", "nonce", "expires"}
RULE_KEYS = {"v", "kind", "id", "kinds", "tool", "pattern", "scope", "expires"}
TARGET = "agents"
ALL_AGENTS = "*"
AGENT_LIMIT = 50
SETTINGS_FILE = "/.claude/settings.json"
SETTINGS_KEYS = ("file", "base", "changes")
SETTINGS_SECTIONS = ("permissions", "sandbox")
SETTINGS_LISTS = ("permissions.allow", "permissions.ask", "permissions.deny", "sandbox.filesystem.allowWrite", "sandbox.filesystem.denyRead", "sandbox.network.allowedDomains")
SETTINGS_OPS = ("add", "remove")
CHANGE_KEYS = ("list", "op", "entry")
CHANGE_LIMIT = 50
ENTRY = re.compile(r"(?=[^\x00-\x1f\x7f\ud800-\udfff]*\S)[^\x00-\x1f\x7f\ud800-\udfff]{1,500}")
SETTINGS_PATH = re.compile(r"/[^\x00-\x1f\x7f\ud800-\udfff]{0,4095}")
SURROGATE = re.compile(r"[\ud800-\udfff]")
UNSEEN = ("Cc", "Cf", "Zl", "Zp")
DEFAULT_IGNORABLE = ((0xAD, 0xAD), (0x34F, 0x34F), (0x61C, 0x61C), (0x115F, 0x1160), (0x17B4, 0x17B5), (0x180B, 0x180F), (0x200B, 0x200F), (0x202A, 0x202E), (0x2060, 0x206F), (0x3164, 0x3164), (0xFE00, 0xFE0F), (0xFEFF, 0xFEFF), (0xFFA0, 0xFFA0), (0xFFF0, 0xFFF8), (0x1BCA0, 0x1BCA3), (0x1D173, 0x1D17A), (0xE0000, 0xE0FFF))
IGNORABLE = frozenset(code for start, end in DEFAULT_IGNORABLE for code in range(start, end + 1))
EMOJI_TABLE = Path(__file__).with_name("emoji-variation.json")
HEX_CODE = re.compile(r"[0-9A-F]{4,6}")
PRESENTATION = (chr(0xFE0E), chr(0xFE0F))
FREE_TEXT = ("command", "text", "reason", "question", "description")
BREAKS = "\t\n"
DEPTH_LIMIT = 64
WARNINGS = (
("deletes recursively", re.compile(r"\brm\s+(?:-\S+\s+)*-\S*[rR]")),
("forces", re.compile(r"--force\b|\bpush\b.*\s-f\b")),
@@ -284,6 +308,283 @@ def rule_payload(rule_id: str, kinds: list[str], tool: str, pattern: str, scope:
return {"v": VERSION, "kind": "rule", "id": rule_id, "kinds": kinds, "tool": tool, "pattern": pattern, "scope": scope, "expires": expires}
def targeted(rule: dict, agents: list[str]) -> dict:
"""Args:
rule: a rule_payload().
agents: [ALL_AGENTS], or the sorted session ids of one agent or of a
named group, resolved when the operator signs.
Returns:
The rule payload limited to those agents.
"""
return {**rule, TARGET: agents}
def enable_item(rule: dict) -> dict:
"""Args:
rule: the signed payload of a stored rule.
Returns:
The item a fresh approval lists to turn exactly that rule on again.
"""
return {"kind": "enable", "rule": rule}
def agents_problem(agents: object) -> str | None:
"""Returns:
Why agents is neither [ALL_AGENTS] nor 1 to AGENT_LIMIT sorted,
distinct session ids, or None.
"""
if agents == [ALL_AGENTS]:
return None
if not isinstance(agents, list) or not 1 <= len(agents) <= AGENT_LIMIT or not all(isinstance(agent, str) and SESSION.fullmatch(agent) for agent in agents):
return f'agents must be ["{ALL_AGENTS}"] or 1 to {AGENT_LIMIT} session ids'
return None if agents == sorted(set(agents)) else "agents must be sorted and distinct"
def checked_target(rule: dict) -> None:
"""Raises:
Refused when the rule carries agents that agents_problem() refuses.
"""
problem = agents_problem(rule[TARGET]) if TARGET in rule else None
if problem:
raise Refused(f"the rule names no target: {problem}")
def item_sessions(item: dict) -> set[str]:
"""Returns:
The session an ask comes from; empty for every other item, which
names none.
"""
return {item["session"]} if item["kind"] == "ask" else set()
def reaches(rule: dict, sessions: set[str]) -> bool:
"""Args:
rule: a checked rule payload.
sessions: the sessions the item comes from; empty when the item names
none, which only a rule for every agent reaches.
Returns:
True when the rule carries no agents or [ALL_AGENTS], or names one of
the sessions.
"""
return TARGET not in rule or rule[TARGET] == [ALL_AGENTS] or bool(sessions & set(rule[TARGET]))
def settings_item(file: str, base: str, changes: list[dict]) -> dict:
return {"kind": "settings", "file": file, "base": base, "changes": changes}
def unseen(char: str) -> bool:
"""Returns:
True for a character no prompt shows as itself: a category of UNSEEN,
a space separator other than the space, or a code point of
DEFAULT_IGNORABLE; page-reveal.js marks the same set.
"""
category = unicodedata.category(char)
return category in UNSEEN or (category == "Zs" and char != " ") or ord(char) in IGNORABLE
def emoji_base(code: int) -> bool:
return 0x7F < code <= 0x10FFFF and not 0xD800 <= code <= 0xDFFF and not unseen(chr(code))
def variation_table(path: Path) -> frozenset[int]:
"""Args:
path: the emoji variation table, a JSON object whose bases list the
hex code points of emoji-variation-sequences.txt.
Returns:
The bases as code points.
Raises:
ValueError when bases is no list of hex strings, or names an ASCII
code point, a surrogate or one unseen() names; like a missing file,
this stops the module from loading, so no selector is ever accepted
after an unchecked base.
"""
bases = json.loads(path.read_text(encoding="utf-8"))["bases"]
if not isinstance(bases, list) or not all(isinstance(code, str) and HEX_CODE.fullmatch(code) for code in bases):
raise ValueError(f"{path}: bases must be a list of hex code points")
codes = frozenset(int(code, 16) for code in bases)
wrong = sorted(code for code in codes if not emoji_base(code))
if wrong:
raise ValueError(f"{path}: U+{wrong[0]:04X} is no visible non-ASCII emoji base")
return codes
EMOJI_BASES = variation_table(EMOJI_TABLE)
def presented(text: str, index: int) -> bool:
"""Returns:
True when text[index] is a variation selector of PRESENTATION right
after a code point of EMOJI_BASES, a standardized emoji variation
sequence such as the stopwatch of the score block that every prompt
draws as the symbol itself; page-reveal.js skips the same pairs.
"""
return text[index] in PRESENTATION and index > 0 and ord(text[index - 1]) in EMOJI_BASES
def hidden_char(text: str, name: str) -> str | None:
"""Returns:
The first character of text that unseen() names, a tab or a line
break only outside the FREE_TEXT fields, and no presented() selector;
None when there is none.
"""
allowed = BREAKS if name in FREE_TEXT else ""
return next((char for index, char in enumerate(text) if unseen(char) and char not in allowed and not presented(text, index)), None)
def removal(value: dict) -> bool:
return set(value) == set(CHANGE_KEYS) and value["op"] == "remove" and value["list"] in SETTINGS_LISTS
def hidden_problem(value: object, name: str) -> str | None:
"""Args:
value: a text, or an object or list of them, that reaches a signed
payload or the approval prompt; an object's texts are named by
their keys. Only the entry of a settings change of op remove is
exempt: removing an allow entry narrows access, but removing a
deny, ask or denyRead entry widens it, and that is safe only
because the writer removes exactly the signed text and the page
marks every character unseen() names.
name: the field a text sits in.
Returns:
Why the first text holding a character unseen() names (a bidi
control, a zero-width character, a carriage return, a no-break space,
a Hangul filler) is refused, since the prompt would show other text
than what is signed; None when no text holds one.
"""
if isinstance(value, dict):
named = {key: child for key, child in value.items() if not (key == "entry" and removal(value))}
return next(filter(None, (hidden_problem(child, str(key)) for key, child in named.items())), None)
if isinstance(value, list):
return next(filter(None, (hidden_problem(child, name) for child in value)), None)
hidden = hidden_char(value, name) if isinstance(value, str) else None
return None if hidden is None else f"{name} must hold no invisible, format, control or look-alike character such as U+{ord(hidden):04X}, which shows other text than what is signed"
def settings_file_problem(file: object) -> str | None:
if not isinstance(file, str) or not SETTINGS_PATH.fullmatch(file) or not file.endswith(SETTINGS_FILE):
return f"file must be the absolute path of a {SETTINGS_FILE.lstrip('/')}"
if any(part in f"{file}/" for part in ("/../", "/./", "//")):
return "file must name no . or .. and no empty part"
return hidden_problem(file, "file")
def change_problem(change: object) -> str | None:
if not isinstance(change, dict) or set(change) != set(CHANGE_KEYS) or not all(isinstance(change[name], str) for name in CHANGE_KEYS):
return "a change holds exactly list, op and entry as text"
if change["list"] not in SETTINGS_LISTS or change["op"] not in SETTINGS_OPS:
return f"list must be one of {', '.join(SETTINGS_LISTS)} and op one of {', '.join(SETTINGS_OPS)}"
return hidden_problem(change, "change") if ENTRY.fullmatch(change["entry"]) else "entry must be one line of 1 to 500 characters"
def settings_problem(item: object) -> str | None:
"""Args:
item: {"file", "base", "changes"}: file the absolute path of a
.claude/settings.json, base the sha256 of its bytes or "" while it
is missing, changes 1 to CHANGE_LIMIT {"list", "op", "entry"},
each list and entry once.
Returns:
Why the item is malformed, or None; the hub and the writer check it
the same way.
"""
if not isinstance(item, dict) or set(item) != set(SETTINGS_KEYS):
return "a settings change holds exactly file, base and changes"
if not isinstance(item["base"], str) or not (item["base"] == "" or HASH.fullmatch(item["base"])):
return "base must be the sha256 of the file, or empty for a missing file"
return settings_file_problem(item["file"]) or changes_problem(item["changes"])
def changes_problem(changes: object) -> str | None:
if not isinstance(changes, list) or not 1 <= len(changes) <= CHANGE_LIMIT:
return f"changes must list 1 to {CHANGE_LIMIT} changes"
problem = next(filter(None, map(change_problem, changes)), None)
if problem:
return problem
pairs = {(change["list"], change["entry"]) for change in changes}
return None if len(pairs) == len(changes) else "each list and entry is changed once"
def settings_view(settings: dict) -> dict:
"""Returns:
The permissions and sandbox sections of a settings object, the only
part of the file the Agent Orchestrator receives.
"""
return {name: settings[name] for name in SETTINGS_SECTIONS if isinstance(settings.get(name), dict)}
def plain_problem(value: object, depth: int) -> str | None:
"""Args:
value: a parsed JSON value.
depth: how many objects and lists hold it.
Returns:
Why value is unsafe to copy or write, a lone surrogate in any text or
more than DEPTH_LIMIT levels, or None.
"""
if isinstance(value, str):
return "the file holds a lone surrogate" if SURROGATE.search(value) else None
if not isinstance(value, (dict, list)):
return None
if depth >= DEPTH_LIMIT:
return f"the file nests deeper than {DEPTH_LIMIT} levels"
children = [*value, *value.values()] if isinstance(value, dict) else value
return next(filter(None, (plain_problem(child, depth + 1) for child in children)), None)
def plain_copy(settings: dict) -> dict:
"""Raises:
Refused for settings plain_problem() refuses, before deepcopy could
recurse into them.
"""
problem = plain_problem(settings, 0)
if problem:
raise Refused(problem)
return copy.deepcopy(settings)
def apply_changes(settings: dict, changes: list[dict]) -> dict:
"""Args:
settings: the parsed settings object.
changes: changes settings_problem() accepts.
Returns:
A copy of settings with each change applied in order and every other
key kept.
Raises:
Refused when settings nest deeper than DEPTH_LIMIT or hold a lone
surrogate, an object on a list's path is no object, a list holds
anything but text, an added entry is listed already or a removed one
is not.
"""
result = plain_copy(settings)
for change in changes:
*path, leaf = change["list"].split(".")
node = result
for name in path:
node = node.setdefault(name, {})
if not isinstance(node, dict):
raise Refused(f"{name} is no object")
entries = node.setdefault(leaf, [])
if not isinstance(entries, list) or not all(isinstance(entry, str) for entry in entries):
raise Refused(f"{change['list']} is no list of texts")
listed = change["entry"] in entries
if listed == (change["op"] == "add"):
raise Refused(f"{change['list']} {'lists' if listed else 'does not list'} {change['entry']}")
if listed:
entries.remove(change["entry"])
else:
entries.append(change["entry"])
return result
def warnings(command: str) -> list[str]:
return [label for label, pattern in WARNINGS if pattern.search(command)]
@@ -311,8 +612,9 @@ def checked_approval(payload: object, now: float) -> dict:
def checked_rule(payload: object, now: float) -> dict:
if not isinstance(payload, dict) or set(payload) != RULE_KEYS or payload["v"] != VERSION or payload["kind"] != "rule":
if not isinstance(payload, dict) or set(payload) - {TARGET} != RULE_KEYS or payload["v"] != VERSION or payload["kind"] != "rule":
raise Refused("the payload is no rule")
checked_target(payload)
if not isinstance(payload["id"], str) or not ID.fullmatch(payload["id"]):
raise Refused("the rule holds no id")
kinds = payload["kinds"]
@@ -325,6 +627,10 @@ def checked_rule(payload: object, now: float) -> dict:
def rule_allows(rule: dict, item: dict, gate: str, now: float) -> bool:
return reaches(rule, item_sessions(item)) and pattern_allows(rule, item, gate, now)
def pattern_allows(rule: dict, item: dict, gate: str, now: float) -> bool:
if rule["expires"] <= now or item["kind"] not in rule["kinds"]:
return False
if item["kind"] == "ask":