Hugging Face's logo

Spaces:
solidprivacy
/
scrub
Running

App Files Community
scrub / DOCX_HYGIENE_AUDIT_UI_PLAN.md
solidprivacy-nl
Fix DOCX hygiene UI plan real-data wording contract
272a9da
preview code
|
Raw
History Blame
7.67 kB

WP39B — DOCX hygiene audit UI planning

Status: completed planning/documentation-only
Repository: solidprivacy-nl/scrub

This plan describes how the existing report-only DOCX hygiene audit can be shown in the Streamlit app in a later implementation package.

This package does not implement UI, cleaning, export blocking, export/download changes, Scrub Key changes, reinsert behavior changes, dependencies, cloud processing or real-data fixtures.

1. Purpose

WP37 and WP38 made hidden DOCX hygiene risk visible in helper/report form. WP39 defined that current DOCX output must not be described as clean DOCX export.

WP39B plans the future UI surface for that audit.

Goal:

Show DOCX hygiene risk clearly before users trust or share DOCX output, without changing export behavior yet.

The UI must help users understand that DOCX can contain hidden or side-channel content such as headers, footers, comments and tracked changes.

2. Existing helper to use later

Future implementation should use the existing helper:

build_docx_hygiene_audit_report(content: bytes) -> dict
render_docx_hygiene_audit_markdown(report: dict) -> str

Source:

docx_hygiene_audit.py

Important helper boundaries already defined by WP38:

report_only: true
extraction_only: true
cleaning_applied: false
export_blocking: false
export_semantics_changed: false
safe_to_claim_clean: false

The UI must preserve these boundaries.

3. Placement in the current workflow

Future UI should show the DOCX hygiene audit only when DOCX bytes are available.

Recommended placement in the anonymization/export flow:

  1. After upload of a DOCX file and before DOCX export buttons.
  2. Near Download opgeschoond Word-bestand (.docx).
  3. In a compact section titled:
DOCX-hygiënecontrole — rapportage, geen schoonmaak

Recommended placement in the reinsert flow:

  1. Near restored DOCX output/download controls.
  2. Below the existing DOCX limitation warning.
  3. With the same report-only boundary text.

The section should be collapsed by default when severity is low and expanded by default when severity is medium or high.

4. Minimum visible UI content

The future UI should show a compact summary first:

Er is een DOCX-hygiënerapport beschikbaar.
Dit rapport controleert ondersteunde verborgen DOCX-onderdelen.
Dit is geen schone-DOCX garantie.
Er is geen schoonmaak toegepast.
Er is geen exportblokkade toegepast.

Minimum fields:

severity
summary.message
report_only
cleaning_applied
export_blocking
safe_to_claim_clean
counts.headers
counts.footers
counts.comments
counts.tracked_changes
unsupported_scope_note

Findings should be shown as a compact list with:

finding.title
finding.severity
finding.count
finding.risk
finding.recommended_action

5. Dutch labels

Recommended Dutch UI labels:

DOCX-hygiënecontrole — rapportage, geen schoonmaak
Risiconiveau
Verborgen onderdelen gevonden
Kopteksten
Voetteksten
Opmerkingen / kantlijncommentaren
Wijzigingen bijhouden
Aanbevolen controle
Rapport downloaden
Geen schone-DOCX garantie

Required boundary labels:

Rapportage-only
Geen schoonmaak toegepast
Geen exportblokkade toegepast
Geen opmerkingen of wijzigingen verwijderd
Geen wijziging aan Scrub Key
Geen wijziging aan terugzetten/originele waarden

Forbidden labels until later approved implementation:

Schone DOCX
Veilige DOCX
Volledig opgeschoonde DOCX
Metadata-vrij
Opmerkingen verwijderd
Wijzigingen verwijderd
Verborgen inhoud verwijderd

6. Severity behavior

The future UI should map helper severity as follows.

low

Meaning:

No WP37-supported hidden-content findings were detected.

Required warning:

Geen ondersteunde verborgen DOCX-onderdelen gevonden, maar dit is geen schone-DOCX garantie.

UI behavior:

  • compact info message;
  • section collapsed by default;
  • export/download buttons remain unchanged.

medium

Meaning:

DOCX hygiene risk could not be fully assessed.

Required warning:

DOCX-hygiënerisico kon niet volledig worden beoordeeld. Claim het bestand niet als schoon.

UI behavior:

  • warning message;
  • section expanded by default;
  • export/download buttons remain unchanged.

high

Meaning:

Headers, footers, comments or tracked changes were detected.

Required warning:

Verborgen of moeilijk zichtbare DOCX-inhoud is gevonden. Controleer dit vóór delen of exporteren.

UI behavior:

  • high-risk warning;
  • section expanded by default;
  • finding list visible;
  • export/download buttons remain unchanged.

7. Export/download policy

WP39B does not change export/download behavior.

Future implementation may show or download an audit report, but only as report output. It must not silently change DOCX output bytes, filenames, MIME types, or export availability.

Allowed future UI actions:

Bekijk DOCX-hygiënerapport
Download DOCX-hygiënerapport (.txt or .md)

Not allowed in WP39B or the first UI implementation unless separately approved:

Blokkeer export
Maak schoon DOCX-bestand
Verwijder opmerkingen
Accepteer/verwijder bijgehouden wijzigingen
Verwijder metadata
Wijzig DOCX output bytes
Wijzig Scrub Key mapping
Wijzig reinsert output

8. Implementation constraints for later package

A later UI implementation should be small and helper-driven.

Technical direction:

from docx_hygiene_audit import build_docx_hygiene_audit_report, render_docx_hygiene_audit_markdown

Allowed inputs:

uploaded DOCX bytes already provided by the user in the current session
restored DOCX bytes already produced locally in the current session

Forbidden:

  • no cloud document processing;
  • no AI calls;
  • no persistence of document bytes;
  • no new dependencies;
  • no raw HTML rendering of user document content;
  • no export blocking;
  • no cleaning/removal;
  • no mutation of review table state;
  • no mutation of Scrub Key state;
  • no mutation of reinsert output.

Additional implementation boundaries:

  • no cloud document processing
  • no AI calls
  • no persistence of document bytes
  • no real data
  • no cloud processing
  • real-data fixtures are forbidden
  • uploaded DOCX bytes already provided by the user in the current session may be audited report-only

9. Suggested future contract tests

Before UI implementation, add a contract-test package such as:

WP39C — DOCX hygiene audit UI contract tests

Suggested test file:

tests/test_docx_hygiene_audit_ui_plan.py

Minimum contract checks:

  • plan says report-only;
  • plan says no cleaning applied;
  • plan says no export blocking;
  • plan says no clean-DOCX guarantee;
  • plan forbids clean/safe/metadata-free wording;
  • plan requires safe_to_claim_clean: false;
  • plan requires unsupported-scope note;
  • plan requires high-risk findings for headers, footers, comments and tracked changes;
  • plan forbids Scrub Key changes;
  • plan forbids reinsert behavior changes;
  • plan forbids cloud processing and real data.

10. Recommended next step

Recommended next package:

WP39C — DOCX hygiene audit UI contract tests

Only after those contract tests are green and coordinator approval is explicit should a later package implement a small Streamlit UI surface.

Potential later implementation package:

WP39D — DOCX hygiene audit UI implementation

The later implementation must remain report-only unless a separate approved policy package changes export-blocking or clean-DOCX semantics.