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

+36 -13
View File
@@ -8,12 +8,13 @@ from .choosing import answer_signed
from .cleanup import cleanup_request
from .denying import DENIABLE, DENY_KEYS, denial_note, request_status, request_words
from .errors import Conflict, Missing, ToolError
from .fields import decode, expect, field
from .fields import decode, expect, field, visible
from .firewall import settings_request
from .gating import gate_request
from .offices import office_request
from .records import digest, shown
from .register import REGISTER, adder, operator_rows, read_register, runnable
from .rules import rule_matches, subject_of
from .rules import enable_request, rule_matches, subject_of
from .signed import (
ask_signed,
operator_signed,
@@ -63,7 +64,12 @@ class Approving:
"""Returns:
The approval payload over the items, its WebAuthn challenge and the
pinned credential ids; payload and challenge are None for no item.
Raises:
ToolError from visible() for an item holding a text no prompt
shows as signed, whatever source missed it.
"""
visible(items)
credentials = [key["id"] for key in self.keys()]
if not items:
return {"payload": None, "challenge": None, "credentials": credentials}
@@ -131,7 +137,7 @@ class Approving:
def automate(self, kind_name: str, record: dict) -> None:
now = time.time()
subject = subject_of(kind_name, record)
subject = subject_of(kind_name, record, self.deciders(kind_name, record))
rule = next((rule for rule in self.rules.listed() if rule_matches(rule, kind_name, subject, now)), None)
if rule is None:
return
@@ -189,6 +195,27 @@ class Approving:
raise Conflict({"id": raw["id"], "status": "recipient changed", "to": name})
return name
def operator_entry(self, raw: dict, tasks: dict[str, dict]) -> dict:
"""Args:
raw: a checked inbox entry of kind operator.
tasks: the register.
Returns:
The signed item of the operator row raw names, once its task,
command and directory pass visible().
"""
row = next((row for row in operator_rows(tasks) if row["task"] == raw["id"]), None)
if row is None:
raise Missing(str(raw["id"]))
visible({name: row[name] for name in ("task", "command", "directory")})
if raw["verb"] == "approve" and not runnable(row):
raise ToolError("an operator row is approved only when it holds a directory and a command")
if digest(row["command"]) != raw["sha256"]:
raise Conflict({"id": row["task"], "status": "changed"})
if row["task"] in self.open_jobs():
raise Conflict({"id": row["task"], "status": "queued"})
return inbox_item(raw, "", row["command"], "", operator_signed(row), self.requester(raw, adder(tasks[row["task"]])))
def item_of(self, raw: object, tasks: dict[str, dict]) -> dict:
if not isinstance(raw, dict):
raise ToolError("every item must be an object with kind, id, verb, label and sha256, and a denial also channel, reason and to")
@@ -197,16 +224,7 @@ class Approving:
if kind_name not in INBOX_KINDS or verb not in VERBS or not isinstance(raw["label"], str) or not isinstance(raw["sha256"], str):
raise ToolError(f"kind must be one of {', '.join(INBOX_KINDS)}, verb approve or reject, label and sha256 text")
if kind_name == "operator":
row = next((row for row in operator_rows(tasks) if row["task"] == raw["id"]), None)
if row is None:
raise Missing(str(raw["id"]))
if verb == "approve" and not runnable(row):
raise ToolError("an operator row is approved only when it holds a directory and a command")
if digest(row["command"]) != raw["sha256"]:
raise Conflict({"id": row["task"], "status": "changed"})
if row["task"] in self.open_jobs():
raise Conflict({"id": row["task"], "status": "queued"})
return inbox_item(raw, "", row["command"], "", operator_signed(row), self.requester(raw, adder(tasks[row["task"]])))
return self.operator_entry(raw, tasks)
if kind_name == "rule" and verb == "approve":
raise ToolError("a rule request is accepted in its row, with the passkey signature over the rule itself")
item_id = field(raw, "id")
@@ -253,6 +271,11 @@ class Approving:
signed = self.task_changes(raw)
elif gate_request(raw):
signed = self.gate_changes(raw)
elif settings_request(raw):
signed = self.settings_changes(raw)
elif enable_request(raw):
signed = self.enable_items(raw)
return {**self.challenge_for(signed), "enables": signed[0]["rule"]}
else:
signed = [item["signed"] for item in self.checked(raw) if item["signed"] is not None]
return self.challenge_for(signed)
+6 -1
View File
@@ -16,6 +16,7 @@ from .fields import (
instant,
message_text,
seconds,
visible,
)
from .signed import ask_signed
@@ -55,7 +56,9 @@ def option_of(option: object) -> dict:
raise ToolError("every option must be an object with label and description")
expect(option, ("label", "description"))
label = field(option, "label").strip()
return {"label": label, "description": bounded(option, "description", DESCRIPTION_LIMIT).strip()}
description = bounded(option, "description", DESCRIPTION_LIMIT).strip()
visible({"description": description})
return {"label": label, "description": description}
class Asking:
@@ -64,6 +67,7 @@ class Asking:
diff = valid_diff(payload.pop("diff")) if "diff" in payload else None
expect(payload, ("tool", *ASK_TEXTS, "timeout"))
values = {name: bounded(payload, name, limit) for name, limit in ASK_TEXTS.items()}
visible(values)
lifetime = seconds(payload, "timeout", ASK_LIFETIME)
created = time.time()
fields = {**values, "tool": field(payload, "tool").strip(), "status": "pending", "decided": None, "proof": None, "diff_files": None if diff is None else len(diff)}
@@ -104,6 +108,7 @@ class Asking:
def decision_request(self, arguments: dict) -> dict:
expect(arguments, ("question", "options", "agent", "recommended"))
question = message_text(arguments, "question")
visible({"question": question})
options = arguments["options"]
if not isinstance(options, list) or not 1 <= len(options) <= OPTION_LIMIT:
raise ToolError(f"options must be a list of 1 to {OPTION_LIMIT} objects")
+17 -1
View File
@@ -5,7 +5,7 @@ import math
import re
from .errors import ToolError
from .signed import limits
from .signed import limits, signing
WAIT_CAP = 300
TEXT_LIMIT = 20_000
@@ -43,9 +43,25 @@ def field(arguments: dict, name: str) -> str:
value = arguments[name]
if not isinstance(value, str) or not pattern.fullmatch(value):
raise ToolError(f"{name} must be {hint}")
visible({name: value})
return value
def visible(value: object) -> None:
"""Args:
value: an object of named texts, or a list of them, that reaches a
signed payload or the approval prompt.
Raises:
ToolError with the reason signing.hidden_problem() gives for the
first text holding an invisible, format, control or look-alike
character.
"""
hidden = signing.hidden_problem(value, "value")
if hidden:
raise ToolError(hidden)
def bounded(arguments: dict, name: str, limit: int) -> str:
value = arguments[name]
if not isinstance(value, str) or len(value) > limit:
+248
View File
@@ -0,0 +1,248 @@
from __future__ import annotations
import difflib
import json
import re
import secrets
import time
from .errors import Conflict, Missing, ToolError
from .fields import decode, expect, visible
from .ledger import Ledger
from .records import read_json, stamp
from .rules import EVERY_AGENT, RULE_KINDS
from .signed import signing
VIEW = "view.json"
JOB_VERSION = 1
ITEM_LIMIT = 10
SET_LIMIT = 50
DAY_LIMIT = 366
NAME = re.compile(r"(?=[^\x00-\x1f\x7f]*\S)[^\x00-\x1f\x7f]{1,80}")
RULE_TEXT = re.compile(r"(?P<tool>[^()]+?)(?:\((?P<spec>.*)\))?", re.DOTALL)
WORD = re.compile(r"[\s:]")
HASH = re.compile(r"[0-9a-f]{64}")
PERMISSION_LISTS = ("allow", "ask", "deny")
SET_KEYS = ("kind", "tool", "pattern", "scope")
CHAINED = "chains, pipes, redirects or substitutions"
def settings_request(raw: object) -> bool:
return isinstance(raw, list) and bool(raw) and all(isinstance(entry, dict) and entry.get("kind") == "settings" for entry in raw)
def tool_and_prefix(entry: str) -> tuple[str, str]:
"""Returns:
The tool of a permission rule such as Bash(git push:*) and the first
word of its specifier, for Bash the command; "" without specifier.
"""
found = RULE_TEXT.fullmatch(entry)
if found is None:
return entry.strip(), ""
return found.group("tool").strip(), WORD.split((found.group("spec") or "").strip(), maxsplit=1)[0]
def grouped(permissions: object) -> list[dict]:
"""Returns:
The allow, ask and deny entries of a permissions section grouped by
tool and prefix, sorted: [{"tool", "prefix", "entries": [{"list",
"entry"}]}].
"""
groups: dict[tuple[str, str], list[dict]] = {}
lists = permissions if isinstance(permissions, dict) else {}
for name in PERMISSION_LISTS:
values = lists.get(name)
for entry in values if isinstance(values, list) else []:
if isinstance(entry, str):
groups.setdefault(tool_and_prefix(entry), []).append({"list": name, "entry": entry})
return [{"tool": tool, "prefix": prefix, "entries": entries} for (tool, prefix), entries in sorted(groups.items())]
def sandbox_entries(section: object, path: str) -> list[dict]:
"""Returns:
Every leaf of a sandbox section under the dotted path, a list as
{"key", "values"} and any other value as {"key", "value"}.
"""
found: list[dict] = []
for name, value in section.items() if isinstance(section, dict) else ():
key = f"{path}.{name}"
if isinstance(value, dict):
found += sandbox_entries(value, key)
elif isinstance(value, list):
found.append({"key": key, "values": [entry if isinstance(entry, str) else json.dumps(entry) for entry in value]})
else:
found.append({"key": key, "value": value})
return found
def shaped_file(entry: object) -> bool:
if not isinstance(entry, dict) or not isinstance(entry.get("path"), str) or not isinstance(entry.get("exists"), bool):
return False
return isinstance(entry.get("settings"), dict) and isinstance(entry.get("sha256"), str) and (entry["sha256"] == "" or bool(HASH.fullmatch(entry["sha256"])))
def section_diff(path: str, before: dict, after: dict) -> str:
"""Returns:
The unified diff of the permissions and sandbox sections before and
after the change, as the host writer applies it.
"""
lines = difflib.unified_diff(json.dumps(before, indent=2).splitlines(), json.dumps(after, indent=2).splitlines(), fromfile=path, tofile=path, lineterm="", n=3)
return "\n".join(lines)
def unique_name(payload: dict, ledger: Ledger) -> str:
name = payload["name"]
if not isinstance(name, str) or not NAME.fullmatch(name):
raise ToolError("name must be one line of 1 to 80 characters")
visible({"name": name})
if any(record["name"] == name for record in ledger.listed()):
raise Conflict({"name": name, "status": "exists"})
return name
def dropped(ledger: Ledger, record_id: str) -> dict:
if not ledger.remove(record_id):
raise Missing(record_id)
return {"id": record_id, "deleted": True}
def deny_patterns() -> list[dict]:
"""Returns:
The commands no ask rule ever grants, as {"label", "pattern"}.
"""
return [*({"label": label, "pattern": pattern.pattern} for label, pattern in signing.WARNINGS), {"label": CHAINED, "pattern": signing.CHAINED.pattern}]
class Firewall:
def settings_files(self) -> tuple[list[dict], dict]:
"""Returns:
The listed settings files the host writer last read, each
{"path", "exists", "sha256", "error", "settings"} with settings
only their permissions and sandbox sections, and the view's
written time and error.
"""
view = read_json(self.firewall_spool.root / VIEW)
files = view.get("files") if isinstance(view, dict) else None
if not isinstance(files, list):
return [], {"written": None, "error": "no settings view yet: the kvb-orchestrator-firewall unit writes it on the host"}
shown = [{**entry, "settings": signing.settings_view(entry["settings"]), "error": str(entry.get("error") or "")} for entry in files if shaped_file(entry)]
return shown, {"written": view.get("written"), "error": ""}
def firewall(self) -> dict:
files, meta = self.settings_files()
listed = [{key: entry[key] for key in ("path", "exists", "sha256", "error")} | {"groups": grouped(entry["settings"].get("permissions")), "sandbox": sandbox_entries(entry["settings"].get("sandbox"), "sandbox")} for entry in files]
return {**meta, "files": listed, "lists": list(signing.SETTINGS_LISTS), "patterns": deny_patterns(), "groups": self.groups.listed(), "sets": self.rule_sets.listed()}
def settings_changes(self, raw: object) -> list[dict]:
"""Args:
raw: the page's items, each {"kind": "settings", "file", "base",
"changes"} for one listed file at the sha256 the view shows.
Returns:
The signed items, each one file whose changes apply to the
sections the view shows.
"""
if not isinstance(raw, list) or not 1 <= len(raw) <= ITEM_LIMIT:
raise ToolError(f"items must be a list of 1 to {ITEM_LIMIT} settings changes")
files = {entry["path"]: entry for entry in self.settings_files()[0]}
signed: list[dict] = []
for entry in raw:
if not isinstance(entry, dict):
raise ToolError("every item must be an object with kind, file, base and changes")
expect(entry, ("kind", *signing.SETTINGS_KEYS))
order = {name: entry[name] for name in signing.SETTINGS_KEYS}
problem = signing.settings_problem(order)
if problem:
raise ToolError(problem)
self.applicable(files, order)
if any(item["file"] == order["file"] for item in signed):
raise ToolError("one item per file: list every change of a file in its changes")
signed.append(signing.settings_item(**order))
return signed
def applicable(self, files: dict[str, dict], order: dict) -> dict:
shown = files.get(order["file"])
if shown is None:
raise ToolError(f"{order['file'][:300]} is no settings file the Firewall lists")
if shown["sha256"] != order["base"]:
raise Conflict({"file": order["file"], "status": "changed", "sha256": shown["sha256"]})
try:
return signing.apply_changes(shown["settings"], order["changes"])
except signing.Refused as error:
raise ToolError(str(error)) from None
def settings_preview(self, body: bytes) -> dict:
payload = decode(body)
expect(payload, ("items",))
items = self.settings_changes(payload["items"])
files = {entry["path"]: entry for entry in self.settings_files()[0]}
return {"diffs": [{"file": item["file"], "diff": section_diff(item["file"], files[item["file"]]["settings"], self.applicable(files, item))} for item in items]}
def change_settings(self, body: bytes) -> dict:
payload = decode(body)
expect(payload, ("items", "proof"))
items = self.settings_changes(payload["items"])
proof = self.covered(payload["proof"], items, time.time())
for item in items:
self.operator_proven(proof, item)
job_id = secrets.token_hex(8)
job = {"v": JOB_VERSION, "id": job_id, "created": stamp(), "items": [{name: item[name] for name in signing.SETTINGS_KEYS} for item in items], "proof": proof}
self.firewall_spool.put(job_id, job)
lines = [f"{item['file']}: {change['op']} {change['list']} {change['entry']}" for item in items for change in item["changes"]]
self.log.add({"kind": "run", "title": f"Settings change signed: {len(lines)}"[:200], "text": "\n".join(lines), "ref": {"firewall": job_id, "status": "queued"}})
return {"id": job_id, "status": "queued", "items": job["items"]}
def settings_state(self, job_id: str) -> dict:
result = read_json(self.firewall_spool.results / f"{job_id}.json")
if isinstance(result, dict) and isinstance(result.get("items"), list):
return {**result, "id": job_id, "status": "done"}
if (self.firewall_spool.jobs / f"{job_id}.json").is_file():
return {"id": job_id, "status": "queued", "items": []}
raise Missing(job_id)
def add_group(self, body: bytes) -> dict:
"""Args:
body: {"name", "members"}: members 1 to signing.AGENT_LIMIT
sorted session ids the Agent Orchestrator knows.
"""
payload = decode(body)
expect(payload, ("name", "members"))
members = payload["members"]
problem = signing.agents_problem(members) if members != EVERY_AGENT else "members must name sessions, not every agent"
if problem:
raise ToolError(problem)
self.known_agents(members)
record = self.groups.add({"name": unique_name(payload, self.groups), "members": members})
self.log.add({"kind": "rule", "title": f"Agent group {record['name']}: {len(members)} agents", "text": ", ".join(members), "ref": {"group": record["id"]}})
return record
def add_set(self, body: bytes) -> dict:
"""Args:
body: {"name", "days", "rules"}: the ids of 1 to SET_LIMIT stored
rules whose kind, tool, pattern and scope the set keeps, and
the lifetime in days each rule gets when the set is taken
over and signed for an agent, a group or every agent.
"""
payload = decode(body)
expect(payload, ("name", "days", "rules"))
days = payload["days"]
if isinstance(days, bool) or not isinstance(days, int) or not 1 <= days <= DAY_LIMIT:
raise ToolError(f"days must be a whole number from 1 to {DAY_LIMIT}")
chosen = self.stored_rules(payload["rules"])
record = self.rule_sets.add({"name": unique_name(payload, self.rule_sets), "days": days, "rules": [{key: rule[key] for key in SET_KEYS} for rule in chosen]})
self.log.add({"kind": "rule", "title": f"Rule set {record['name']}: {len(chosen)} rules", "text": "\n".join(f"{rule['kind']} {rule['tool']} {rule['pattern']}".replace(" ", " ") for rule in chosen), "ref": {"set": record["id"]}})
return record
def stored_rules(self, ids: object) -> list[dict]:
if not isinstance(ids, list) or not 1 <= len(ids) <= SET_LIMIT or len(set(map(str, ids))) != len(ids):
raise ToolError(f"rules must list 1 to {SET_LIMIT} distinct rule ids")
chosen = [self.rules.get(rule_id) if isinstance(rule_id, str) else None for rule_id in ids]
if None in chosen or any(rule["kind"] not in RULE_KINDS for rule in chosen):
raise ToolError("rules must name stored rules")
return chosen
def drop_group(self, group_id: str) -> dict:
return dropped(self.groups, group_id)
def drop_set(self, set_id: str) -> dict:
return dropped(self.rule_sets, set_id)
+29 -3
View File
@@ -64,8 +64,13 @@ SETTINGS_SIGN_ROUTE = "/api/settings/sign"
CHOICES_ROUTE = "/api/choices"
CHOICES_SIGN_ROUTE = "/api/choices/sign"
DIFF_ROUTE = re.compile(r"/api/diffs/(review|ask)/([0-9a-f]{16})")
FIREWALL_ROUTE = "/api/firewall"
FIREWALL_POSTS = {"/api/firewall/preview": "settings_preview", "/api/firewall/settings": "change_settings", "/api/firewall/groups": "add_group", "/api/firewall/sets": "add_set"}
FIREWALL_STATE = re.compile(r"/api/firewall/settings/([0-9a-f]{16})")
FIREWALL_DROP = re.compile(r"/api/firewall/(groups|sets)/([0-9a-f]{16})/delete")
FIREWALL_STATUS = {"settings_preview": HTTPStatus.OK, "change_settings": HTTPStatus.ACCEPTED, "add_group": HTTPStatus.CREATED, "add_set": HTTPStatus.CREATED}
WAV_POSTS = (STT_ROUTE, VOICE_ROUTE)
ACTION_POSTS = ("/api/rules", "/api/nl", SETTINGS_ROUTE, TTS_ROUTE, STT_ROUTE, SIGN_ROUTE, RULE_SIGN_ROUTE, CLEANUP_ROUTE, OFFICES_ROUTE, TASKS_ROUTE, VOICE_ROUTE, MESSAGE_SIGN_ROUTE, SETTINGS_SIGN_ROUTE, CHOICES_ROUTE, CHOICES_SIGN_ROUTE, GATES_ROUTE, TOKEN_ROUTE)
ACTION_POSTS = ("/api/rules", "/api/nl", SETTINGS_ROUTE, TTS_ROUTE, STT_ROUTE, SIGN_ROUTE, RULE_SIGN_ROUTE, CLEANUP_ROUTE, OFFICES_ROUTE, TASKS_ROUTE, VOICE_ROUTE, MESSAGE_SIGN_ROUTE, SETTINGS_SIGN_ROUTE, CHOICES_ROUTE, CHOICES_SIGN_ROUTE, GATES_ROUTE, TOKEN_ROUTE, *FIREWALL_POSTS)
class Handler(Exchange):
@@ -93,10 +98,13 @@ class Handler(Exchange):
office = OFFICE_STATE.fullmatch(path)
voice = VOICE_ITEM.fullmatch(path)
diff = DIFF_ROUTE.fullmatch(path)
firewall = self.firewall_reader(path)
if self.host() is None:
self.send_text(HTTPStatus.FORBIDDEN, "forbidden host")
elif path == "/":
self.index()
elif firewall:
self.answer(firewall, HTTPStatus.OK)
elif diff:
self.answer(lambda: hub.diff_of(diff.group(1), diff.group(2)), HTTPStatus.OK)
elif vendored and vendored.group(1) in VENDOR:
@@ -197,7 +205,7 @@ class Handler(Exchange):
if path == "/api/rules":
return lambda body: self.answer(lambda: hub.add_rule(body), HTTPStatus.CREATED)
if rule:
return lambda _body: self.answer(lambda: hub.rule_action(rule.group(1), rule.group(2)), HTTPStatus.OK)
return lambda body: self.answer(lambda: hub.rule_action(rule.group(1), rule.group(2), body), HTTPStatus.OK)
if path == "/api/nl":
return lambda body: self.answer(lambda: hub.nl(body), HTTPStatus.OK)
if path == SETTINGS_ROUTE:
@@ -216,10 +224,28 @@ class Handler(Exchange):
return lambda body: self.answer(lambda: hub.sign_choices(body), HTTPStatus.OK)
if path == CHOICES_ROUTE:
return lambda body: self.answer(lambda: hub.request_choices(body), HTTPStatus.CREATED)
return self.firewall_action(path)
def firewall_reader(self, path: str) -> Callable[[], dict] | None:
hub = self.server.hub
job = FIREWALL_STATE.fullmatch(path)
if path == FIREWALL_ROUTE:
return hub.firewall
return (lambda: hub.settings_state(job.group(1))) if job else None
def firewall_action(self, path: str) -> Callable[[bytes], None] | None:
hub = self.server.hub
drop = FIREWALL_DROP.fullmatch(path)
if path in FIREWALL_POSTS:
method = getattr(hub, FIREWALL_POSTS[path])
return lambda body: self.answer(lambda: method(body), FIREWALL_STATUS[FIREWALL_POSTS[path]])
if drop:
remove = hub.drop_group if drop.group(1) == "groups" else hub.drop_set
return lambda _body: self.answer(lambda: remove(drop.group(2)), HTTPStatus.OK)
return None
def posted(self, path: str) -> bool:
return any(pattern.fullmatch(path) for pattern in (INBOX_ROUTE, UNDO_ROUTE, RULE_ROUTE, REQUEST_ROUTE, RUNNER_ROUTE))
return any(pattern.fullmatch(path) for pattern in (INBOX_ROUTE, UNDO_ROUTE, RULE_ROUTE, REQUEST_ROUTE, RUNNER_ROUTE, FIREWALL_DROP))
def runner(self, path: str, body: bytes) -> None:
hub = self.server.hub
+11 -2
View File
@@ -19,6 +19,7 @@ from .crons import History, queue_live
from .denying import Denying
from .engines import Engines, Speech
from .events import Log, Watch
from .firewall import Firewall
from .gating import Gating
from .icons import sheet
from .inbox import Inbox
@@ -43,7 +44,7 @@ from .redirects import Redirects
from .requesting import Requesting
from .resources import RESOURCES, SAMPLES
from .reviewing import Reviewing
from .rules import Rules
from .rules import Offers, Rules
from .settings import Settings
from .signed import signing
from .skill_scripts import Runner
@@ -81,7 +82,7 @@ def environment(templates: Path) -> jinja2.Environment:
@dataclass(frozen=True)
class Hub(Mcp, Reviewing, Asking, Messaging, Choosing, Approving, Denying, Requesting, Cleaning, Offices, Tasking, Gating, Inbox, Rules, Jobs, Sources, Timeline, View, Language):
class Hub(Mcp, Reviewing, Asking, Messaging, Choosing, Approving, Denying, Requesting, Cleaning, Offices, Tasking, Gating, Firewall, Inbox, Rules, Jobs, Sources, Timeline, View, Language):
council: Path
pages: Path
public_port: int
@@ -96,6 +97,7 @@ class Hub(Mcp, Reviewing, Asking, Messaging, Choosing, Approving, Denying, Reque
scripts: Runner
templates: jinja2.Environment
rules: Ledger
offers: Offers
jobs: Ledger
marks: Marks
log: Log
@@ -118,6 +120,9 @@ class Hub(Mcp, Reviewing, Asking, Messaging, Choosing, Approving, Denying, Reque
icons: Markup
spool: Spool
office_spool: Spool
firewall_spool: Spool
groups: Ledger
rule_sets: Ledger
touched: Touched
voice_notes: VoiceNotes
replay: Path
@@ -160,6 +165,9 @@ def open_hub(council: Path, pages: Path, public_port: int, state: Path, host_sta
icons=sheet(places.vendor, templates),
spool=Spool(places.cleanup).ready(),
office_spool=Spool(places.offices).ready(),
firewall_spool=Spool(state / "firewall").ready(),
groups=Ledger(state / "groups.json"),
rule_sets=Ledger(state / "rule-sets.json"),
touched=Touched(reviews.stored),
approvers=approvers,
speech=speech,
@@ -167,6 +175,7 @@ def open_hub(council: Path, pages: Path, public_port: int, state: Path, host_sta
replay=state / "replay" / "messages.json",
view_store=ViewStore(state / "view.json"),
rules=Ledger(state / "rules.json"),
offers=Offers(),
jobs=Ledger(state / "jobs.json"),
marks=Marks(state / "marks.json"),
log=Log(state / "log.jsonl"),
+5 -6
View File
@@ -6,7 +6,7 @@ from .denying import request_status, request_words, requester_of
from .errors import Conflict, Missing, ToolError
from .fields import WAIT_CAP, bounded, decode, expect, field, seconds
from .records import iso_epoch
from .rules import rule_fields, rule_matches, signed_fields, subject_of
from .rules import EVERY_AGENT, rule_fields, rule_matches, signed_fields, subject_of
from .signed import signing
# Trip-wire: MCP carries no caller identity, so an agent may name itself anew for each request; AGENT_CAP only spreads the queue, TOTAL_CAP is the bound.
@@ -33,7 +33,7 @@ class Requesting:
def rule_request(self, arguments: dict) -> dict:
expect(arguments, (*RULE_FIELDS, "agent", "why"))
now = time.time()
fields = rule_fields(arguments, now)
fields = {name: value for name, value in rule_fields(arguments, EVERY_AGENT, now).items() if name in RULE_FIELDS}
if fields["kind"] == "decision" and fields["scope"] != "*":
raise ToolError("a decision rule takes scope *, as the rules form does")
name = field(arguments, "agent").strip()
@@ -71,7 +71,7 @@ class Requesting:
rule = {**{key: record[key] for key in RULE_FIELDS}, "enabled": True, "proof": {"payload": payload, "assertion": None}}
ledger = {"ask": self.asks, "review": self.reviews, "decision": self.decisions}[kind_name]
since = now - RECENT_DAYS * 86400
subjects = [subject_of(kind_name, entry) for entry in ledger.listed() if created_of(entry) >= since]
subjects = [subject_of(kind_name, entry, self.deciders(kind_name, entry)) for entry in ledger.listed() if created_of(entry) >= since]
return {"matched": sum(rule_matches(rule, kind_name, subject, now) for subject in subjects), "total": len(subjects), "days": RECENT_DAYS}
def request_items(self, base: dict, now: float, claims: list[dict]) -> list[dict]:
@@ -95,7 +95,7 @@ class Requesting:
def sign_request(self, request_id: str) -> dict:
record = self.pending_request(request_id)
return {**self.rule_offer(rule_fields(record, time.time())), "sign": True}
return {**self.rule_offer(rule_fields(record, EVERY_AGENT, time.time())), "sign": True}
def accept_request(self, request_id: str, body: bytes) -> dict:
payload = decode(body)
@@ -106,9 +106,8 @@ class Requesting:
fields = signed_fields(rule, now)
if [fields[key] for key in RULE_FIELDS] != [record[key] for key in RULE_FIELDS]:
raise ToolError("the signed rule must be exactly the requested one")
if self.rules.get(rule["id"]) is not None:
raise Conflict({"id": rule["id"], "status": "exists"})
proof = self.proven_rule(rule, payload["assertion"])
self.offered(rule, now)
decided, changed = self.rule_requests.decide(request_id, {"status": "accepted", "rule": rule["id"]})
if not changed:
raise Conflict(request_state(decided, now))
+160 -16
View File
@@ -1,13 +1,19 @@
from __future__ import annotations
import fnmatch
import threading
import time
from .council import read_claims
from .errors import Conflict, Missing, ToolError
from .fields import COMMAND_LIMIT, PATH_LIMIT, bounded, decode, expect
from .fields import COMMAND_LIMIT, PATH_LIMIT, bounded, decode, expect, visible
from .names import Directory
from .signed import ask_signed, passkey, review_signed, signing, verifier
RULE_KINDS = ("ask", "review", "decision")
RULE_INPUT = ("kind", "tool", "pattern", "scope", "expires")
EVERY_AGENT = [signing.ALL_AGENTS]
OFFER_LIMIT = 1000
def rule_matches(rule: dict, kind_name: str, subject: dict, now: float) -> bool:
@@ -15,31 +21,73 @@ def rule_matches(rule: dict, kind_name: str, subject: dict, now: float) -> bool:
if not rule["enabled"] or rule["expires"] <= now or rule["kind"] != kind_name or proof is None:
return False
if kind_name == "decision":
return subject["recommended"] != "" and fnmatch.fnmatchcase(subject["agent"], rule["pattern"])
named = subject["recommended"] != "" and fnmatch.fnmatchcase(subject["agent"], rule["pattern"])
return named and signing.reaches(proof["payload"], subject["sessions"])
return signing.rule_allows(proof["payload"], subject["item"], subject["gate"], now)
def subject_of(kind_name: str, record: dict) -> dict:
def subject_of(kind_name: str, record: dict, sessions: set[str]) -> dict:
"""Args:
kind_name: ask, review or decision.
record: the ask, review or decision.
sessions: for a decision, the sessions that held the asking agent's
name; empty for an ask or review, whose signed item names its own.
Returns:
What a rule of that kind is matched against.
"""
if kind_name == "ask":
return {"item": ask_signed(record), "gate": ""}
if kind_name == "review":
return {"item": review_signed(record), "gate": record.get("gate", "")}
return {"recommended": record["recommended"], "agent": record["agent"]}
return {"recommended": record["recommended"], "agent": record["agent"], "sessions": sessions}
def rule_fields(raw: dict, now: float) -> dict:
def rule_fields(raw: dict, agents: object, now: float) -> dict:
"""Args:
raw: kind, tool, pattern, scope and expires of the rule.
agents: EVERY_AGENT, or the sorted session ids of one agent or group.
now: the current time in epoch seconds.
Returns:
The checked fields with agents.
"""
kind_name, expires = raw["kind"], raw["expires"]
if kind_name not in RULE_KINDS:
raise ToolError(f"kind must be one of {', '.join(RULE_KINDS)}")
tool_name, pattern, scope = rule_texts(raw, kind_name)
if isinstance(expires, bool) or not isinstance(expires, int | float) or not now + 1 < expires <= now + signing.RULE_LIFETIME:
raise ToolError("expires must be a moment within the next 366 days")
return {"kind": kind_name, "tool": tool_name, "pattern": pattern, "scope": scope, "expires": int(expires), "agents": target_of(kind_name, agents)}
def rule_texts(raw: dict, kind_name: str) -> tuple[str, str, str]:
"""Returns:
tool, pattern and scope of raw, once each is one line without a
control, format, line or paragraph separator character, as visible()
checks, and only an ask rule names a tool.
"""
tool_name = bounded(raw, "tool", 200).strip()
if (kind_name == "ask") != bool(tool_name):
raise ToolError("an ask rule names a tool; review and decision rules leave tool empty")
pattern, scope = bounded(raw, "pattern", COMMAND_LIMIT), bounded(raw, "scope", PATH_LIMIT)
if not pattern.strip() or not scope.strip() or "\n" in pattern or "\n" in scope:
raise ToolError("pattern and scope must be one non-empty line each")
if isinstance(expires, bool) or not isinstance(expires, int | float) or not now + 1 < expires <= now + signing.RULE_LIFETIME:
raise ToolError("expires must be a moment within the next 366 days")
return {"kind": kind_name, "tool": tool_name, "pattern": pattern, "scope": scope, "expires": int(expires)}
visible({"tool": tool_name, "pattern": pattern, "scope": scope})
return tool_name, pattern, scope
def target_of(kind_name: str, agents: object) -> list[str]:
"""Returns:
agents, once signing.agents_problem() accepts it and a review rule
names every agent, since a review names no session.
"""
problem = signing.agents_problem(agents)
if problem:
raise ToolError(problem)
if kind_name == "review" and agents != EVERY_AGENT:
raise ToolError("a review rule applies to every agent: a review names no session")
return agents
def signed_fields(rule: object, now: float) -> dict:
@@ -49,17 +97,77 @@ def signed_fields(rule: object, now: float) -> dict:
raise ToolError(f"rule: {error}") from None
if len(rule["kinds"]) != 1:
raise ToolError("a rule names exactly one kind")
fields = rule_fields({**{name: rule[name] for name in ("tool", "pattern", "scope", "expires")}, "kind": rule["kinds"][0]}, now)
agents = EVERY_AGENT
if signing.TARGET in rule:
agents = rule[signing.TARGET]
fields = rule_fields({**{name: rule[name] for name in ("tool", "pattern", "scope", "expires")}, "kind": rule["kinds"][0]}, agents, now)
if fields["tool"] != rule["tool"]:
raise ToolError("tool must not carry surrounding blanks")
return fields
class Offers:
def __init__(self) -> None:
self.lock = threading.Lock()
self.ids: dict[str, float] = {}
def offer(self, rule_id: str, now: float) -> None:
"""Args:
rule_id: an id the hub just put into a rule payload for the
operator to sign; held in memory only, so a hub restart
forgets every offer and refuses their proofs.
now: the current time; offers older than signing.LIFETIME and
beyond the newest OFFER_LIMIT are dropped.
"""
with self.lock:
self.ids = {key: at for key, at in self.ids.items() if now - at <= signing.LIFETIME}
self.ids[rule_id] = now
while len(self.ids) > OFFER_LIMIT:
del self.ids[next(iter(self.ids))]
def take(self, rule_id: str, now: float) -> bool:
with self.lock:
offered = self.ids.pop(rule_id, None)
return offered is not None and now - offered <= signing.LIFETIME
class Rules:
def rule_offer(self, fields: dict) -> dict:
rule = signing.rule_payload(self.rules.fresh(), [fields["kind"]], fields["tool"], fields["pattern"], fields["scope"], fields["expires"])
rule = signing.targeted(signing.rule_payload(self.rules.fresh(), [fields["kind"]], fields["tool"], fields["pattern"], fields["scope"], fields["expires"]), fields["agents"])
visible(rule)
self.offers.offer(rule["id"], time.time())
return {"payload": rule, "challenge": signing.challenge(rule), "credentials": [key["id"] for key in self.keys()]}
def offered(self, rule: dict, now: float) -> None:
"""Raises:
Conflict unless the hub offered the rule's id and stored no rule
under it since, so a signed rule is stored once and never again
after its deletion.
"""
if not self.offers.take(rule["id"], now):
raise Conflict({"id": rule["id"], "status": "not offered or already stored: sign the rule anew"})
def deciders(self, kind_name: str, record: dict) -> set[str]:
"""Returns:
For a decision, the one session that holds its agent's name now,
none when no session or several hold it; empty for every other
kind.
"""
if kind_name != "decision":
return set()
directory = Directory(self.names.listed())
holders = {session for session in directory.aliases(record["agent"]) if directory.now(session) == record["agent"]}
return holders if len(holders) == 1 else set()
def known_agents(self, agents: list[str]) -> None:
"""Raises:
ToolError unless agents is EVERY_AGENT or every session in it is
one the Agent Orchestrator knows.
"""
unknown = sorted(set(agents) - self.office_sessions(read_claims(self.council))) if agents != EVERY_AGENT else []
if unknown:
raise ToolError(f"agents must be sessions the Agent Orchestrator knows: {', '.join(unknown)[:200]}")
def proven_rule(self, rule: dict, assertion: object) -> dict:
"""Args:
rule: the rule payload, already checked by signed_fields.
@@ -80,8 +188,11 @@ class Rules:
def sign_rule(self, body: bytes) -> dict:
payload = decode(body)
expect(payload, ("kind", "tool", "pattern", "scope", "expires"))
return {**self.rule_offer(rule_fields(payload, time.time())), "sign": True}
targeted = "agents" in payload
expect(payload, (*RULE_INPUT, "agents") if targeted else RULE_INPUT)
fields = rule_fields(payload, payload["agents"] if targeted else EVERY_AGENT, time.time())
self.known_agents(fields["agents"])
return {**self.rule_offer(fields), "sign": True}
def add_rule(self, body: bytes) -> dict:
payload = decode(body)
@@ -91,16 +202,49 @@ class Rules:
fields = signed_fields(rule, now)
if not isinstance(payload["enabled"], bool):
raise ToolError("enabled must be true or false")
if self.rules.get(rule["id"]) is not None:
raise Conflict({"id": rule["id"], "status": "exists"})
return self.store_rule(rule, fields, self.proven_rule(rule, payload["assertion"]), payload["enabled"], now)
proof = self.proven_rule(rule, payload["assertion"])
self.offered(rule, now)
return self.store_rule(rule, fields, proof, payload["enabled"], now)
def rule_action(self, rule_id: str, verb: str) -> dict:
def enable_items(self, raw: list[dict]) -> list[dict]:
"""Args:
raw: [{"kind": "enable", "rule"}] with the id of a stored rule.
Returns:
The item a fresh approval signs to turn that rule on.
"""
expect(raw[0], ("kind", "rule"))
return [self.enable_subject(raw[0]["rule"])]
def enable_subject(self, rule_id: object) -> dict:
record = self.rules.get(rule_id) if isinstance(rule_id, str) else None
if record is None:
raise Missing(str(rule_id)[:40])
if record.get("proof") is None:
raise ToolError("an unsigned rule grants nothing: sign it anew")
return signing.enable_item(record["proof"]["payload"])
def rule_action(self, rule_id: str, verb: str, body: bytes) -> dict:
"""Args:
rule_id: the stored rule.
verb: delete, disable, or enable, which widens what agents may
do and so needs {"proof"}: a fresh passkey approval listing
signing.enable_item() of the rule.
body: the request body.
"""
if verb == "delete":
if not self.rules.remove(rule_id):
raise Missing(rule_id)
return {"id": rule_id, "deleted": True}
if verb == "enable":
payload = decode(body)
expect(payload, ("proof",))
self.operator_proven(payload["proof"], self.enable_subject(rule_id))
record = self.rules.change(rule_id, {"enabled": verb == "enable"})
if record is None:
raise Missing(rule_id)
return record
def enable_request(raw: object) -> bool:
return isinstance(raw, list) and len(raw) == 1 and isinstance(raw[0], dict) and raw[0].get("kind") == "enable"
+1 -1
View File
@@ -226,5 +226,5 @@ class View:
def render(self, nonce: str) -> tuple[str, str]:
now = time.time()
state = self.state(now - RADIO_WINDOW, now, now, 0)
page = self.templates.get_template("index.html.j2").render(nonce=nonce, state=state, view=self.view_store.get(), icons=self.icons)
page = self.templates.get_template("index.html.j2").render(nonce=nonce, state=state, view=self.view_store.get(), icons=self.icons, emoji_bases=sorted(signing.EMOJI_BASES))
return page, INDEX_CSP.format(nonce, " ".join(["'self'", *state["media"]]))