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

+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":