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

+6 -5
View File
@@ -15,9 +15,10 @@
with the repository, worktree, branch and tree as git prints them
here, the notes file's text (refused past NOTES_LIMIT characters),
and the diff of the tree git write-tree prints against HEAD
(staged_diff.tree_diff, content withheld per the MEDUSA rules under
<dir>, by default those of the pipx install); without the diff when
the body would pass DIFF_BODY_LIMIT.
(staged_diff.tree_diff, secrets masked per the MEDUSA rules under
<dir>, by default those of the pipx install) with the sealed clear
patches of its masked files apart; without either when the body
would pass DIFF_BODY_LIMIT.
Returns:
pin: exit code 0 and the pinned credential on stdout; 1 and the reason
@@ -89,14 +90,14 @@ def request_review(args: argparse.Namespace) -> str:
item = staged(cwd, "0" * 16)
try:
notes = args.notes.read_text(encoding="utf-8")
diff = staged_diff.tree_diff(cwd, item["tree"], args.rules or staged_diff.rules_root())
diff, sealed = staged_diff.tree_diff(cwd, item["tree"], args.rules or staged_diff.rules_root())
except (OSError, ValueError, staged_diff.DiffError) as error:
raise Refused(f"the review cannot be prepared: {error}") from error
if len(notes) > NOTES_LIMIT:
raise Refused(f"the notes hold {len(notes)} characters, the hub takes at most {NOTES_LIMIT}")
arguments = {key: item[key] for key in ("repo", "worktree", "branch", "tree")}
arguments.update(title=args.title, page=str(args.page), notes=notes, gate=args.gate, score=args.score, agent=args.agent)
body = review_body({**arguments, "diff": diff})
body = review_body({**arguments, "diff": diff, "sealed": sealed})
if len(body) > DIFF_BODY_LIMIT:
print(f"approval: the review goes without its diff, its {len(body)} bytes pass the hub's {DIFF_BODY_LIMIT}", file=sys.stderr)
body = review_body(arguments)
+10 -1
View File
@@ -9,12 +9,21 @@
NOTES_LIMIT: characters of review notes the hub takes; the client refuses
longer notes instead of cutting them.
WITHHELD: the note of a diff entry that ships without its patch because
its content may hold a secret.
no secret rule loads to mask it.
MASKED: the note of a diff entry whose patch reads MASK for every secret
rule match and every armour block line.
MASK: what stands for a masked span in a patch.
SEALED_LIMIT: bytes of JSON-encoded clear patch text of the masked and
withheld files one request carries apart from its diff, for a
signed reveal.
"""
DIFF_LIMIT = 2 << 20
DIFF_BODY_LIMIT = 4 << 20
SEALED_LIMIT = 1 << 20
FILE_CAP = 5000
PATH_LIMIT = 4096
NOTES_LIMIT = 100_000
WITHHELD = "content withheld"
MASKED = "masked"
MASK = "••••"
+9 -6
View File
@@ -18,9 +18,10 @@ Returns:
takes or a hub that is down, so Claude Code shows its own dialog.
The exit code is 0. An ask for a Bash git commit of exactly the
staged index (staged_diff.commit_of) carries the diff staged_diff.py
builds of the tree its directory stages, content withheld per the
MEDUSA rules of the pipx install; none when it cannot be built or
the body would pass DIFF_BODY_LIMIT. An allow of such an ask turns
builds of the tree its directory stages, secrets masked per the
MEDUSA rules of the pipx install, and the sealed clear patches of
its masked files apart; neither when it cannot be built or the body
would pass DIFF_BODY_LIMIT. An allow of such an ask turns
into a deny with CHANGED when what the commit records
(staged_diff.binding) differs right before answering from the
preview's, and with UNBOUND when either cannot be read. Any other
@@ -88,8 +89,9 @@ def unapprovable(ask: dict) -> bool:
def commit_diff(ask: dict, rules: Path | None) -> tuple[str | None, dict]:
"""Returns:
For a commit ask, what the commit records (staged_diff.binding, None
when it cannot be read) and {"diff": the preview of exactly that},
{} when it cannot be built; None and {} for any other ask.
when it cannot be read) and {"diff": the preview of exactly that,
"sealed": the clear patches of its masked files}, {} when it cannot
be built; None and {} for any other ask.
"""
target = commit_target(ask)
if target is None:
@@ -100,7 +102,8 @@ def commit_diff(ask: dict, rules: Path | None) -> tuple[str | None, dict]:
print(f"kvb-orchestrator: the ask goes without its diff and an allow of it turns into a deny: {error}", file=sys.stderr)
return None, {}
try:
return pinned, {"diff": staged_diff.bound_diff(target, pinned, rules)}
diff, sealed = staged_diff.bound_diff(target, pinned, rules)
return pinned, {"diff": diff, "sealed": sealed}
except FAILURES as error:
print(f"kvb-orchestrator: the ask goes without its diff: {error}", file=sys.stderr)
return pinned, {}
+137 -35
View File
@@ -6,19 +6,24 @@
pinned: for bound_diff, what binding returned for the same cwd.
Returns:
review_diff, tree_diff, bound_diff: the review diff of requirement 003
of the staged tree against HEAD (git diff --cached), one {path,
status, mode, additions, deletions, patch, note} per changed path,
sorted by path, status A, M, D or B (binary); path is the file name
with bytes that are no UTF-8 written as backslash escapes; mode the
git file mode, "old => new" when it changed. patch holds the unified
hunks; it is empty for a binary file, a gitlink, a side over
BLOB_LIMIT bytes (counted 0/0), a path sandbox_paths denies (its
FLOOR and the settings' deny lists) and every file past DIFF_LIMIT
bytes of JSON-encoded patch text. A file whose old or new content
holds an ARMOUR line or matches a MEDUSA secret rule for its name,
and every file when no secret rule pattern loads, ships no patch,
only its counts and the note WITHHELD. The diff fails when more
review_diff, tree_diff, bound_diff: (diff, sealed). diff is the review
diff of requirement 003 of the staged tree against HEAD (git diff
--cached), one {path, status, mode, additions, deletions, patch,
note} per changed path, sorted by path, status A, M, D or B
(binary); path is the file name with bytes that are no UTF-8
written as backslash escapes; mode the git file mode, "old => new"
when it changed. patch holds the unified hunks; it is empty for a
binary file, a gitlink, a side over BLOB_LIMIT bytes (counted 0/0),
a path sandbox_paths denies (its FLOOR and the settings' deny lists)
and every file past DIFF_LIMIT bytes of JSON-encoded patch text. In
a shown line every match of a MEDUSA secret rule for the file's name
and every line from an ARMOUR line through its ARMOUR_END line reads
MASK, and the file carries the note MASKED; when no secret rule
pattern loads, every text file ships no patch, only its counts and
the note WITHHELD. sealed maps the path of each MASKED or WITHHELD
file to its clear patch, while their JSON-encoded text stays within
SEALED_LIMIT bytes; diff never holds a masked span in clear. The
diff fails when more
than FILE_CAP paths changed or one is longer than PATH_LIMIT, a
settings file sandbox_paths reads is unreadable, the working tree
lies under a denied path, HEAD exists but its tree cannot be listed,
@@ -46,9 +51,11 @@ is read.
from __future__ import annotations
import bisect
import difflib
import fnmatch
import hashlib
import itertools
import json
import os
import re
@@ -63,6 +70,9 @@ DIFF_LIMIT = hub_limits.DIFF_LIMIT
FILE_CAP = hub_limits.FILE_CAP
PATH_LIMIT = hub_limits.PATH_LIMIT
WITHHELD = hub_limits.WITHHELD
MASKED = hub_limits.MASKED
MASK = hub_limits.MASK
SEALED_LIMIT = hub_limits.SEALED_LIMIT
BLOB_LIMIT = 2 << 20
BINARY_PROBE = 8000
CONTEXT = 3
@@ -100,8 +110,11 @@ SHORT_ARGS = set("mFcCtuSU")
KEPT_VARS = {"GIT_EDITOR", "GIT_SEQUENCE_EDITOR", "GIT_PAGER", "GIT_TERMINAL_PROMPT", "GIT_AUTHOR_NAME", "GIT_AUTHOR_EMAIL", "GIT_AUTHOR_DATE", "GIT_COMMITTER_NAME", "GIT_COMMITTER_EMAIL", "GIT_COMMITTER_DATE"}
ASSIGNMENT = re.compile(r"([A-Za-z_][A-Za-z0-9_]*)=.*")
ARMOUR = re.compile(r"-----BEGIN [A-Z0-9 ]+-----")
ARMOUR_END = re.compile(r"-----END [A-Z0-9 ]+-----")
HUNK = re.compile(r"@@ -([0-9]+)(?:,[0-9]+)? \+([0-9]+)(?:,[0-9]+)? @@")
Patterns = list[re.Pattern]
Rules = list[tuple[tuple[str, ...], Patterns]]
Spans = list[list[tuple[int, int]]]
class DiffError(Exception):
@@ -200,7 +213,7 @@ def binding(cwd: Path) -> str:
return hashlib.sha256(staged(toplevel(cwd))).hexdigest()
def bound_diff(cwd: Path, pinned: str, rules: Path | None) -> list[dict]:
def bound_diff(cwd: Path, pinned: str, rules: Path | None) -> tuple[list[dict], dict[str, str]]:
index = staged(toplevel(cwd))
if hashlib.sha256(index).hexdigest() != pinned:
raise DiffError("the staged tree changed while its preview was read")
@@ -325,32 +338,114 @@ def rule_patterns(path: str, rules: Rules) -> Patterns:
return [pattern for globs, found in rules if any(fnmatch.fnmatchcase(name, glob.lower()) for glob in globs) for pattern in found]
def withheld(path: str, texts: tuple[str, str], rules: Rules | None) -> bool:
if not rules or not any(patterns for _, patterns in rules):
return True
patterns = [ARMOUR, *rule_patterns(path, rules)]
return any(pattern.search(text) for text in texts for pattern in patterns)
def any_pattern(rules: Rules | None) -> bool:
return bool(rules) and any(patterns for _, patterns in rules)
def entry(head: dict, before: bytes | None, after: bytes | None, rules: Rules | None) -> tuple[dict, list[str]]:
def armour_lines(lines: list[str]) -> set[int]:
"""Returns:
The numbers (from 0) of every line from an ARMOUR line through its
ARMOUR_END line, through the last line when no end follows.
"""
found, inside = set(), False
for number, line in enumerate(lines):
inside = inside or ARMOUR.search(line) is not None
if inside:
found.add(number)
inside = ARMOUR_END.search(line) is None
return found
def hit_spans(text: str, patterns: Patterns) -> Spans:
"""Returns:
Per line of text (text_lines), the [start, end) columns that a match
of a pattern covers, the whole line inside an armour block.
"""
lines = text_lines(text)
spans: Spans = [[] for _ in lines]
starts = list(itertools.accumulate((len(line) + 1 for line in lines), initial=0))
for number in armour_lines(lines):
spans[number].append((0, len(lines[number])))
for pattern in patterns:
for match in pattern.finditer(text):
for number in range(bisect.bisect_right(starts, match.start()) - 1, len(lines)):
if starts[number] >= match.end():
break
begin, end = max(match.start(), starts[number]) - starts[number], min(match.end(), starts[number] + len(lines[number])) - starts[number]
if end > begin:
spans[number].append((begin, end))
return spans
def merged(spans: list[tuple[int, int]]) -> list[tuple[int, int]]:
found: list[tuple[int, int]] = []
for begin, end in sorted(spans):
if found and begin <= found[-1][1]:
found[-1] = (found[-1][0], max(found[-1][1], end))
else:
found.append((begin, end))
return found
def masked(line: str, spans: list[tuple[int, int]]) -> str:
parts, at = [], 0
for begin, end in merged(spans):
parts += [line[at:begin], MASK]
at = end
return "".join([*parts, line[at:]])
def masked_patch(lines: list[str], old: Spans, new: Spans) -> list[str]:
"""Args:
lines: unified diff lines from the first hunk header on.
old, new: hit_spans() of the old and the new text.
Returns:
The lines with every span of their old or new line masked; a
context line takes the spans of both sides.
"""
found, before, after = [], 0, 0
for line in lines:
hunk = HUNK.match(line)
if hunk:
before, after = int(hunk.group(1)) - 1, int(hunk.group(2)) - 1
found.append(line)
continue
sign, spans = line[:1], []
if sign in " -":
spans += old[before]
before += 1
if sign in " +":
spans += new[after]
after += 1
found.append(sign + masked(line[1:], spans) if spans else line)
return found
def entry(head: dict, before: bytes | None, after: bytes | None, rules: Rules | None) -> tuple[dict, list[str], list[str] | None]:
"""Args:
head: the entry's path, status and mode.
Returns:
The diff entry without its patch, and the patch lines; no lines for
a binary side, one over BLOB_LIMIT or content withheld.
The diff entry without its patch, the patch lines to show, and the
clear lines when they differ from those shown (masked or withheld),
else None; no lines for a binary side or one over BLOB_LIMIT.
"""
found = {**head, "additions": 0, "deletions": 0, "note": ""}
if before is None or after is None:
return found, []
return found, [], None
if b"\0" in before[:BINARY_PROBE] or b"\0" in after[:BINARY_PROBE]:
return {**found, "status": "B"}, []
return {**found, "status": "B"}, [], None
texts = (before.decode("utf-8", "replace"), after.decode("utf-8", "replace"))
lines = list(difflib.unified_diff(*map(text_lines, texts), lineterm="", n=CONTEXT))[2:]
found.update(additions=sum(1 for line in lines if line.startswith("+")), deletions=sum(1 for line in lines if line.startswith("-")))
if withheld(head["path"], texts, rules):
return {**found, "note": WITHHELD}, []
return found, lines
if not any_pattern(rules):
return {**found, "note": WITHHELD}, [], lines or None
patterns = rule_patterns(head["path"], rules)
shown = masked_patch(lines, *(hit_spans(text, patterns) for text in texts))
if shown == lines:
return found, lines, None
return {**found, "note": MASKED}, shown, lines
def content_of(side: tuple[str, str] | None, gitlink: bool, contents: dict[str, bytes | None]) -> bytes | None:
@@ -359,11 +454,11 @@ def content_of(side: tuple[str, str] | None, gitlink: bool, contents: dict[str,
return None if gitlink else contents.get(side[1])
def review_diff(cwd: Path, rules: Path | None) -> list[dict]:
def review_diff(cwd: Path, rules: Path | None) -> tuple[list[dict], dict[str, str]]:
return built(cwd, sides(cwd, None, None), rules)
def tree_diff(cwd: Path, tree: str, rules: Path | None) -> list[dict]:
def tree_diff(cwd: Path, tree: str, rules: Path | None) -> tuple[list[dict], dict[str, str]]:
return built(cwd, sides(cwd, tree, None), rules)
@@ -380,7 +475,7 @@ def shown_path(path: str) -> str:
return shown
def path_entry(path: str, before: tuple[str, str] | None, after: tuple[str, str] | None, contents: dict[str, bytes | None], rules: Rules | None) -> tuple[dict, list[str]]:
def path_entry(path: str, before: tuple[str, str] | None, after: tuple[str, str] | None, contents: dict[str, bytes | None], rules: Rules | None) -> tuple[dict, list[str], list[str] | None]:
status = "A" if before is None else "D" if after is None else "M"
gitlink = any(side is not None and side[0] == GITLINK for side in (before, after))
modes = list(dict.fromkeys(side[0] for side in (before, after) if side is not None))
@@ -388,7 +483,11 @@ def path_entry(path: str, before: tuple[str, str] | None, after: tuple[str, str]
return entry(head, content_of(before, gitlink, contents), content_of(after, gitlink, contents), rules)
def built(cwd: Path, found_sides: tuple[dict, dict, dict[str, bytes | None]], rules: Path | None) -> list[dict]:
def encoded_size(text: str) -> int:
return len(json.dumps(text, ensure_ascii=False).encode("utf-8"))
def built(cwd: Path, found_sides: tuple[dict, dict, dict[str, bytes | None]], rules: Path | None) -> tuple[list[dict], dict[str, str]]:
old, new, contents = found_sides
changed = sorted(path for path in {*old, *new} if old.get(path) != new.get(path))
if len(changed) > FILE_CAP:
@@ -397,18 +496,21 @@ def built(cwd: Path, found_sides: tuple[dict, dict, dict[str, bytes | None]], ru
shown_path(path)
fetched(cwd, old, new, changed, contents)
secrets = secret_rules(rules)
diff, spent, full = [], 0, False
diff, sealed, spent, kept, full = [], {}, 0, 0, False
for path in changed:
found, lines = path_entry(path, old.get(path), new.get(path), contents, secrets)
found, lines, clear = path_entry(path, old.get(path), new.get(path), contents, secrets)
patch = "\n".join(lines)
size = len(json.dumps(patch, ensure_ascii=False).encode("utf-8"))
size = encoded_size(patch)
full = full or spent + size > DIFF_LIMIT
if full:
patch = ""
else:
spent += size
diff.append({**found, "patch": patch})
return diff
if clear is not None and kept + encoded_size("\n".join(clear)) <= SEALED_LIMIT:
sealed[found["path"]] = "\n".join(clear)
kept += encoded_size(sealed[found["path"]])
return diff, sealed
def names_commit(command: str) -> bool: