Files
skills/docs/requirements/019-reveal-withheld-diff.md
T
Kevin Veen-BirkenbachandClaude Opus 5.5 af3555e88b 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>
2026-11-17 19:04:35 +00:00

5.2 KiB

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

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.