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

@@ -0,0 +1,110 @@
# 019 - Reveal withheld diff content
## User Story
As the operator, I want a diff file that hits a secret rule to show with only
the hits masked, and the hits shown after a passkey approval per file or per
item, so that I can review every change while no secret reaches the hub page
unasked.
## Decisions (operator-confirmed 2026-11-17; do not re-litigate)
1. **Mask, not withhold**: the client masks only each match of a MEDUSA
secret rule with `••••`, and every PEM armour block from its BEGIN to its
END line; the rest of the patch shows. A file for which no secret rule
loads stays withheld whole (fail closed), but revealable. Rejected:
withholding the whole file by default (hid `tests/test_hub_view.py` over
`tokens = {...}`).
2. **Passkey approval, two scopes**: an eye button per masked file reveals
that file; one button per item reveals every masked file of the review or
ask. The passkey signs `reveal`, kind, id and the paths. Rejected: a plain
confirm click (anyone with page access could reveal).
3. **Sealed store**: the client sends the full patches of the masked files
with the request, kept in a sealed file per item
(`<id>.<kind>-sealed.json`, mode 0600), never in the snapshot, the stream
or `/api/diffs`; the hub deletes it once the item is decided or expires.
Rejected: keeping it with the review (the secret stays on disk longer);
the hub reading git (the hub runs no git by design).
4. **Both kinds**: review diffs (`approval.py`, `tree_diff`) and ask diffs
(`permission_hook.py`, `bound_diff`).
5. **Audit**: every reveal logs an approval-stream event with kind, id and
paths, never the content.
6. **Page memory only**: revealed text stays in page memory until the item
leaves Waits on Operator; never in `localStorage` or the view store.
7. **Timing**: implemented with the other open requirements before the one
final suite plus all e2e on master (operator order 2026-11-17); per
bundle only the MEDUSA scan runs. Rejected: waiting for the 018 commit
(it waits for that same final run).
## Approach
```mermaid
flowchart TD
subgraph P["🧭 0 · Preparation"]
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
P2 -- "✏️ corrections" --> P1
end
P2 -- "🤖 yes, after 018" --> A1
subgraph A["🔐 A · Client masking and sealing"]
A1["🎭 Mask hit spans and armour blocks, seal full patches"] --> A2{"🧪 Unit green?"}
A2 -- "🔴 no: fix" --> A1
end
A2 -- "🟢 yes" --> B1
subgraph B["🗄️ B · Hub sealed store and reveal"]
B1["🔏 Sealed file, signed reveal per file or item, delete on decision"] --> B2{"🧪 Unit green?"}
B2 -- "🔴 no: fix" --> B1
end
B2 -- "🟢 yes" --> C1
subgraph C["👁️ C · Page"]
C1["🖱️ Eye per file, reveal all per item"] --> C2{"🧪 E2E green?"}
C2 -- "🔴 no: fix" --> C1
C2 -- "🟢 yes" --> CF{"💬 Operator feedback on screenshots?"}
CF -- "✏️ changes" --> C1
end
CF -- "👍 fits" --> D1["🏁 Review, commit with operator OK, hand-over"]
```
## Acceptance Criteria
### Client
- [ ] On a file holding `tokens = {"chart": "tokens"}` and an unrelated line,
`tree_diff` and `bound_diff` give a patch where only the match reads
`••••`, note `masked`, and the unrelated line is unchanged.
- [ ] A PEM block masks every line from BEGIN to END; without loadable rules
every text file keeps the note `content withheld` and an empty patch.
- [ ] The request carries the full patches of the masked or withheld files
apart from `diff`; `diff` itself never holds a masked span in clear.
### Hub
- [ ] The sealed file exists with mode 0600 next to the item, is absent from
`/api/diffs/<kind>/<id>`, the snapshot and the stream, and is deleted
after the grant, the denial or the expiry.
- [ ] `POST /api/diffs/<kind>/<id>/reveal` answers the patches only for a
pinned passkey's unexpired, unreplayed signature over `reveal`, kind,
id and exactly the requested paths; a wrong path, a replay, a missing
proof or a decided item answers 4xx without content.
- [ ] Every reveal adds one approval event with kind, id and paths and no
patch text.
### Page
- [ ] A masked file shows its patch with the `••••` spans and an eye button;
an item with 2 or more masked files shows one reveal button; after the
passkey the clear patch replaces the masked one.
- [ ] Revealed text is never written to `localStorage` or the view store and
is gone once the item leaves Waits on Operator.
### Tests
- [ ] Unit: span masking (rule match, armour block, no rules), sealing apart
from `diff`, sealed file mode and deletion per decision path, reveal
signature (per file, per item, wrong path, replay, decided item), audit
event without content.
- [ ] Integration: `approval.py` and the permission hook send masked `diff`
plus the sealed patches to a test hub; a signed reveal returns the
clear patch.
- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390: the masked file with
its eye button, the per-item reveal, the clear patch after the virtual
passkey, no CSP violation; screenshots for the checkpoint.
+1
View File
@@ -22,4 +22,5 @@ skill defines the format.
- [016 - Agents Controls in the View Row](016-agents-controls-row.md)
- [017 - Legend Toggle](017-legend-toggle.md)
- [018 - Gibberlink](018-gibberlink.md)
- [019 - Reveal withheld diff content](019-reveal-withheld-diff.md)
- [021 - TokenEconomizer by default](021-tokeneconomizer-by-default.md)