feat(orchestrator): reveal withheld diff content under a passkey signature (019)

staged_diff masks only the secret rule hits and seals each masked file's clear patch apart; reviews and asks store the sealed patches next to their diff, delete them once the item leaves pending, and the hub sweeps orphans. POST /api/diffs/<kind>/<id>/reveal/sign and /reveal hand the clear patches to a signed request; page-diff.js offers Reveal per hidden file and Reveal all, keeps the clear text in the page only and forgets it once the item leaves the inbox. Requirement 019, unit, hub and e2e tests.

Accepted MEDUSA false positives (security.py accept after kvb-think-criticize, 2026-11-17): approval.py FTSCAN-231 WEB-SSRF RH005; permission_hook.py MM-SCAN-058 WEB-SSRF RH005; staged_diff.py SAST-ENV-001 AI-BACKDOOR-006 B603; hub.py MEX-SCAN-1167 INF-SCAN-589; page-load.js EXA002; hub_case.py TC001-TC009 INF-SCAN-2057/2206/2440/2457 EXA002 EXA006 PL002 B603 FTSC-SCAN-089.

🎯 Fix: 92 %
💥 Break: 4 %
💸 Tokens: –
⏱️ Velocity: –
🛡️ Security: 100 %
🏆 Score: 88
🚦 Gate: ✅ 90/5, tokens and velocity <= 100, security 100 %

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-BirkenbachandClaude Opus 5.5 committed 2026-11-17 19:04:35 +00:00
1 parent 78d4e4a6aa
commit af3555e88b
24 files changed
+928 -111

No files matched your search

+13 -6
View File
@@ -3,7 +3,7 @@ from __future__ import annotations
import time
from .choosing import EVERYONE, answer_text
from .diffs import store_diff, valid_diff
from .diffs import sealed_file, store_diff, store_sealed, valid_diff, valid_sealed
from .errors import Conflict, Missing, ToolError
from .fields import (
COMMAND_LIMIT,
@@ -65,16 +65,20 @@ class Asking:
def ask(self, body: bytes) -> dict:
payload = decode(body)
diff = valid_diff(payload.pop("diff")) if "diff" in payload else None
sealed = valid_sealed(payload.pop("sealed"), diff) if "sealed" in payload else {}
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)}
ask_id = self.asks.fresh()
if diff is not None:
store_diff(self.reviews.pages, "ask", ask_id, diff)
record = self.asks.insert(ask_id, {**fields, "created_ts": created, "expires": created + lifetime})
with self.asks.changed:
ask_id = self.asks.fresh()
if diff is not None:
store_diff(self.reviews.pages, "ask", ask_id, diff)
if sealed:
store_sealed(self.reviews.pages, "ask", ask_id, sealed)
record = self.asks.insert(ask_id, {**fields, "created_ts": created, "expires": created + lifetime})
self.automate("ask", record)
return {"id": record["id"], "status": record["status"]}
@@ -85,7 +89,10 @@ class Asking:
raise Missing(ask_id)
left = max(record["expires"] - time.time(), 0.0)
record = self.asks.wait(ask_id, min(wait or 0.0, WAIT_CAP, left))
return ask_state(record, time.time())
state = ask_state(record, time.time())
if state["status"] == "expired":
sealed_file(self.reviews.pages, "ask", ask_id).unlink(missing_ok=True)
return state
def settle(self, kind_name: str, item_id: str, verb: str, body: bytes) -> dict:
if kind_name == "asks" and verb in ANSWERS:
+40 -3
View File
@@ -10,13 +10,16 @@ from .signed import limits
DIFF_LIMIT = limits.DIFF_LIMIT
DIFF_BODY_LIMIT = limits.DIFF_BODY_LIMIT
SEALED_LIMIT = limits.SEALED_LIMIT
FILE_CAP = limits.FILE_CAP
PATH_LIMIT = limits.PATH_LIMIT
STATUSES = ("A", "M", "D", "R", "B")
DIFF_KEYS = ("path", "status", "mode", "additions", "deletions", "patch", "note")
NOTES = ("", limits.WITHHELD)
HIDDEN = (limits.WITHHELD, limits.MASKED)
NOTES = ("", *HIDDEN)
MODE = re.compile(r"[0-7]{6}(?: => [0-7]{6})?")
DIFF_SUFFIX = {"review": ".review-diff.json", "ask": ".ask-diff.json"}
SEALED_SUFFIX = {"review": ".review-sealed.json", "ask": ".ask-sealed.json"}
def counted(value: object) -> bool:
@@ -33,8 +36,8 @@ def diff_entry(entry: object) -> dict:
raise ToolError("mode must be a git file mode, or old => new for a changed one")
if not counted(entry["additions"]) or not counted(entry["deletions"]) or not isinstance(patch, str) or (entry["status"] == "B" and patch):
raise ToolError("additions and deletions must be counts, patch text, empty for a binary file")
if entry["note"] not in NOTES or (entry["note"] and patch):
raise ToolError(f"note must be empty or {limits.WITHHELD!r}, the latter with an empty patch")
if entry["note"] not in NOTES or (entry["note"] == limits.WITHHELD and patch):
raise ToolError(f"note must be empty, {limits.MASKED!r} or {limits.WITHHELD!r}, the latter with an empty patch")
return {key: entry[key] for key in DIFF_KEYS}
@@ -52,10 +55,44 @@ def valid_diff(value: object) -> list[dict]:
return entries
def valid_sealed(value: object, diff: list[dict] | None) -> dict[str, str]:
"""Returns:
The clear patches a request seals apart from its diff, checked: an
object from the path of a masked or withheld file of diff to its
patch text, at most SEALED_LIMIT bytes of JSON-encoded text in all;
none without a diff.
"""
hidden = {entry["path"] for entry in diff or [] if entry["note"] in HIDDEN}
if not isinstance(value, dict) or not all(isinstance(patch, str) for patch in value.values()) or not set(value) <= hidden:
raise ToolError("sealed must map the path of a masked or withheld file of the diff to its patch text")
if sum(len(json.dumps(patch, ensure_ascii=False).encode("utf-8")) for patch in value.values()) > SEALED_LIMIT:
raise ToolError(f"the sealed patches must stay within {SEALED_LIMIT} bytes")
return dict(value)
def diff_bytes(diff: list[dict]) -> bytes:
return json.dumps({"diff": diff}, ensure_ascii=False).encode("utf-8")
def sealed_bytes(sealed: dict[str, str]) -> bytes:
return json.dumps({"sealed": sealed}, ensure_ascii=False).encode("utf-8")
def sealed_file(folder: Path, kind_name: str, item_id: str) -> Path:
return folder / f"{item_id}{SEALED_SUFFIX[kind_name]}"
def store_sealed(folder: Path, kind_name: str, item_id: str, sealed: dict[str, str]) -> None:
write_atomic(sealed_file(folder, kind_name, item_id), sealed_bytes(sealed))
def stored_sealed(folder: Path, kind_name: str, item_id: str) -> dict[str, str]:
data = read_json(sealed_file(folder, kind_name, item_id))
if not isinstance(data, dict) or not isinstance(data.get("sealed"), dict):
raise Missing(item_id)
return data["sealed"]
def store_diff(folder: Path, kind_name: str, item_id: str, diff: list[dict]) -> None:
write_atomic(folder / f"{item_id}{DIFF_SUFFIX[kind_name]}", diff_bytes(diff))
+6 -1
View File
@@ -67,6 +67,7 @@ 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})")
REVEAL_ROUTE = re.compile(r"/api/diffs/(review|ask)/([0-9a-f]{16})/reveal(/sign)?")
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})")
@@ -175,6 +176,10 @@ class Handler(Exchange):
return lambda body: self.answer(lambda: hub.sign_board(body), HTTPStatus.OK)
if board:
return lambda body: self.answer(lambda: hub.board(board.group(1), body), HTTPStatus.OK)
reveal = REVEAL_ROUTE.fullmatch(path)
if reveal:
method = hub.sign_reveal if reveal.group(3) else hub.reveal
return lambda body: self.answer(lambda: method(reveal.group(1), reveal.group(2), body), HTTPStatus.OK)
return self.inbox_action(path)
def inbox_action(self, path: str) -> Callable[[bytes], None] | None:
@@ -252,7 +257,7 @@ class Handler(Exchange):
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, FIREWALL_DROP))
return any(pattern.fullmatch(path) for pattern in (INBOX_ROUTE, UNDO_ROUTE, RULE_ROUTE, REQUEST_ROUTE, RUNNER_ROUTE, FIREWALL_DROP, REVEAL_ROUTE))
def runner(self, path: str, body: bytes) -> None:
hub = self.server.hub
+5 -3
View File
@@ -17,6 +17,7 @@ from .choosing import Choosing
from .cleanup import Cleaning, Spool
from .crons import History, queue_live
from .denying import Denying
from .diffs import SEALED_SUFFIX
from .engines import Engines, Speech
from .events import Log, Watch
from .firewall import Firewall
@@ -25,7 +26,7 @@ from .icons import sheet
from .inbox import Inbox
from .jobs import Jobs
from .language import Language, Model
from .ledger import Ledger, Marks, Reviews
from .ledger import Ledger, Marks, Reviews, Sealed
from .matching import Matching
from .mcp import Mcp
from .messaging import Messaging
@@ -45,6 +46,7 @@ from .receipts import (
from .redirects import Redirects
from .requesting import Requesting
from .resources import RESOURCES, SAMPLES
from .revealing import Revealing
from .reviewing import Reviewing
from .rules import Offers, Rules
from .settings import Settings
@@ -84,7 +86,7 @@ def environment(templates: Path) -> jinja2.Environment:
@dataclass(frozen=True)
class Hub(Mcp, Reviewing, Asking, Messaging, Choosing, Approving, Denying, Requesting, Cleaning, Offices, Tasking, Gating, Firewall, Inbox, Matching, Rules, Jobs, Sources, Timeline, View, Language):
class Hub(Mcp, Reviewing, Revealing, Asking, Messaging, Choosing, Approving, Denying, Requesting, Cleaning, Offices, Tasking, Gating, Firewall, Inbox, Matching, Rules, Jobs, Sources, Timeline, View, Language):
council: Path
pages: Path
public_port: int
@@ -202,7 +204,7 @@ def open_hub(council: Path, pages: Path, public_port: int, state: Path, host_sta
pages=pages,
public_port=public_port,
reviews=reviews,
asks=Ledger(state / "asks.json"),
asks=Sealed(state / "asks.json", reviews.pages, SEALED_SUFFIX["ask"]),
decisions=Ledger(state / "decisions.json"),
messages=messages,
rule_requests=Ledger(state / "rule-requests.json"),
+22 -4
View File
@@ -6,6 +6,7 @@ import threading
from collections.abc import Callable
from pathlib import Path
from .diffs import SEALED_SUFFIX
from .records import read_json, stamp, write_atomic
@@ -101,11 +102,28 @@ class Ledger:
return dict(self.items[item_id])
class Reviews(Ledger):
class Sealed(Ledger):
def __init__(self, file: Path, pages: Path, suffix: str) -> None:
"""Args:
pages: the folder holding each item's sealed clear patches.
suffix: the name suffix of an item's sealed file there; it is
deleted once the item leaves pending.
"""
super().__init__(file)
self.pages = pages
self.sealed_suffix = suffix
def transition(self, item_id: str, before: str, changes: dict) -> tuple[dict | None, bool]:
record, changed = super().transition(item_id, before, changes)
if changed and record is not None and record.get("status") != "pending":
(self.pages / f"{item_id}{self.sealed_suffix}").unlink(missing_ok=True)
return record, changed
class Reviews(Sealed):
def __init__(self, state: Path) -> None:
super().__init__(state / "reviews.json")
self.pages = state / "pages"
self.pages.mkdir(exist_ok=True)
(state / "pages").mkdir(exist_ok=True)
super().__init__(state / "reviews.json", state / "pages", SEALED_SUFFIX["review"])
def stored(self, review_id: str, suffix: str) -> Path:
return self.pages / f"{review_id}{suffix}"
@@ -0,0 +1,82 @@
from __future__ import annotations
import time
from .asking import ask_state
from .diffs import SEALED_SUFFIX, sealed_file, stored_sealed
from .errors import Conflict, Missing, ToolError
from .fields import decode, expect
from .records import shown
TITLE_LIMIT = 200
PATHS_SHOWN = 2000
def reveal_item(kind_name: str, item_id: str, paths: list[str]) -> dict:
"""Returns:
The item a reveal signs: the sorted paths of one review or ask; its
hash equals no item an executor approves.
"""
return {"kind": "reveal", "target": kind_name, "id": item_id, "paths": paths}
class Revealing:
def sealed_status(self, kind_name: str, item_id: str, now: float) -> tuple[dict | None, str | None]:
record = self.reviews.get(item_id) if kind_name == "review" else self.asks.get(item_id)
if record is None:
return None, None
return record, record["status"] if kind_name == "review" else ask_state(record, now)["status"]
def open_record(self, kind_name: str, item_id: str) -> dict:
"""Returns:
The pending review or ask whose sealed patches a reveal reads.
Raises:
Missing for an unknown item; Conflict once it is decided or
expired, after its sealed file is deleted.
"""
record, status = self.sealed_status(kind_name, item_id, time.time())
if record is None:
raise Missing(item_id)
if status != "pending":
sealed_file(self.reviews.pages, kind_name, item_id).unlink(missing_ok=True)
raise Conflict({"kind": kind_name, "id": item_id, "status": status})
return record
def requested(self, kind_name: str, item_id: str, paths: object) -> tuple[dict, list[str], dict[str, str]]:
record = self.open_record(kind_name, item_id)
if not isinstance(paths, list) or not paths or not all(isinstance(path, str) for path in paths) or len(set(paths)) != len(paths):
raise ToolError("paths must name one or more distinct files")
sealed = stored_sealed(self.reviews.pages, kind_name, item_id)
unsealed = [path for path in paths if path not in sealed]
if unsealed:
raise ToolError(f"nothing sealed to reveal for {shown(unsealed[0])[:TITLE_LIMIT]}")
return record, sorted(paths), sealed
def sign_reveal(self, kind_name: str, item_id: str, body: bytes) -> dict:
payload = decode(body)
expect(payload, ("paths",))
_, paths, _ = self.requested(kind_name, item_id, payload["paths"])
return self.challenge_for([reveal_item(kind_name, item_id, paths)])
def reveal(self, kind_name: str, item_id: str, body: bytes) -> dict:
"""Returns:
The clear patches of exactly the requested paths, once a pinned
passkey signed their reveal_item unexpired and for the first
time; the approval stream records kind, id and paths, never a
patch.
"""
payload = decode(body)
expect(payload, ("paths", "proof"))
record, paths, sealed = self.requested(kind_name, item_id, payload["paths"])
self.operator_proven(payload["proof"], reveal_item(kind_name, item_id, paths))
title = record["title"] if kind_name == "review" else f"{record['tool']}: {record['command']}"
self.log.add({"kind": "approval", "title": f"Reveal {kind_name}: {shown(title)[:TITLE_LIMIT]}", "text": shown(", ".join(paths))[:PATHS_SHOWN], "ref": {"kind": kind_name, "id": item_id, "verb": "reveal", "paths": paths}})
return {"kind": kind_name, "id": item_id, "patches": {path: sealed[path] for path in paths}}
def sweep_sealed(self) -> None:
now = time.time()
for kind_name, suffix in SEALED_SUFFIX.items():
for file in self.reviews.pages.glob(f"*{suffix}"):
if self.sealed_status(kind_name, file.name.removesuffix(suffix), now)[1] != "pending":
file.unlink(missing_ok=True)
+13 -2
View File
@@ -6,7 +6,15 @@ import stat
import time
from pathlib import Path
from .diffs import DIFF_SUFFIX, diff_bytes, stored_diff, valid_diff
from .diffs import (
DIFF_SUFFIX,
SEALED_SUFFIX,
diff_bytes,
sealed_bytes,
stored_diff,
valid_diff,
valid_sealed,
)
from .errors import Conflict, Missing, ToolError
from .fields import WAIT_CAP, bounded, decode, expect, field, seconds
from .review_page import review_files
@@ -17,7 +25,7 @@ NOTES_LIMIT = limits.NOTES_LIMIT
SCORE_LIMIT = 500
GATES = ("pass", "fail")
REQUEST = ("repo", "worktree", "branch", "tree", "title", "page", "notes", "gate", "score")
OPTIONAL = ("agent", "diff")
OPTIONAL = ("agent", "diff", "sealed")
LISTED = ("id", "created", "worktree", "branch", "tree", "title")
STATE = ("id", "status", "tree", "decided")
@@ -67,9 +75,12 @@ class Reviewing:
score = " ".join(bounded(arguments, "score", SCORE_LIMIT).split())
agent = field(arguments, "agent").strip() if "agent" in arguments else ""
diff = valid_diff(arguments["diff"]) if "diff" in arguments else None
sealed = valid_sealed(arguments["sealed"], diff) if "sealed" in arguments else {}
page = self.read_page(field(arguments, "page"))
extra = {"notes": notes, "gate": arguments["gate"], "score": score, "agent": agent, "diff_files": None if diff is None else len(diff)}
attached = {} if diff is None else {DIFF_SUFFIX["review"]: diff_bytes(diff)}
if sealed:
attached[SEALED_SUFFIX["review"]] = sealed_bytes(sealed)
review = self.reviews.submit({**fields, "title": fields["title"].strip(), **extra}, page, review_files(page), attached)
self.automate("review", review)
return {"id": review["id"], "status": review["status"], "url": self.url()}
+1
View File
@@ -77,6 +77,7 @@ class View:
if sampled not in (None, "1"):
raise ToolError("track must be 1 or left out")
self.tree.beat()
self.sweep_sealed()
return self.state(begin, end, now, TRACK_STEPS if sampled else 0)
def inlined(self, news: list[dict], window: tuple[float, float], now: float) -> dict[float, dict]: