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>
111 lines
5.2 KiB
Markdown
111 lines
5.2 KiB
Markdown
# 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.
|