Repository navigation
Privacy and Security
DiffLens is local-first by architecture, not by policy: the code physically cannot send your documents anywhere, and that property is enforced by tooling in CI, not by a promise. This page lays out the threat model and the specific mechanisms.
- Your documents are sensitive (contracts, tenders, financials). They must never leave the machine.
- The app itself runs on your machine, under your user account; the trust boundary is "same user". Defenses against a compromised webview are treated as defense-in-depth.
- The only network-adjacent surface is the Downloads manager (models, sidecar) — and its every byte is checksummed.
- Extraction, alignment, diffing, severity scoring, history and report export are pure local computation. There is no telemetry, no crash reporting, no analytics, no update phone-home.
-
core/src/download/is the only module in the repository allowed to perform HTTP. This invariant is enforced byscripts/audit-egress.sh, which runs as the dedicated egress-audit CI job on every push: any HTTP client code appearing elsewhere fails the build. - The LLM explanation path talks only to a loopback sidecar. Since v1.0.1, only literal
127.0.0.1/[::1]base URLs are accepted — DNS names (evenlocalhost) are rejected so a hostile resolver can never redirect the bearer token — and the guard is re-validated on every call. - The sidecar session key (32 bytes from OS randomness) is handed to the server via the
LLAMA_API_KEYenvironment variable, never the command line, so it cannot be read from the process table.
Every artifact the Downloads manager fetches passes this chain:
-
Pinned manifest — URLs exist only in
resources/manifests/llm-manifest.json, embedded at compile time. The manifest schema requires https, provenance notes, and exactly one primary asset; entries flaggedverified: falseare fatal for primaries and server assets, so a tampered shipped manifest cannot disable checksumming. -
HTTPS fetch into a
.partfile, with size caps enforced up-front (Content-Length vs manifestbytes) and while streaming. -
SHA-256 verification on the
.partfile — before any rename — against the manifest checksum. Mismatch ⇒ part file deleted; nothing becomes "installed". -
Atomic rename into place. Interrupted transfers resume from the
.part; Cancel genuinely aborts (v1.0.1 fix) while keeping the part for resume.
The llama-server bundles arrive as archives, and archives are hostile by default (core/src/download/archive.rs, adversarially tested):
- Path gates reject absolute paths,
..components and prefix escapes. - Per-entry and total size caps are enforced while reading, not from headers (a lying header buys nothing).
- tar symlinks/hardlinks only with relative, allowlisted, in-tree targets; zip symlinks always rejected; setuid/sticky bits stripped.
- Extraction happens into a staging directory that must start empty and is wiped on any failure.
OOXML parsing (DOCX/PPTX/XLSX) has its own zip-bomb budgets (ZipBudget): declared sizes reserved up-front, per-entry caps, lying headers caught by reading one byte past the declared size, XLSX row caps with truncation warnings, 64 MB TXT cap, and roxmltree's default billion-laughs protection.
Exported HTML/Markdown reports embed document-derived text, so escaping is golden-tested against hostile content:
-
html_escapecovers& < > " 'and Unicode bidi override characters (U+202A–E, U+2066–9), in every context including attributes. Reports contain zero JavaScript. - Markdown fences grow past the longest backtick run in the content; table cells escape pipes and newlines.
- OCR rasters are written owner-only (0600) and deleted on drop (v1.0.1).
- The backend validates webview-supplied paths (documents must be existing regular files; export targets must be absolute with matching extension) so a compromised webview gains neither an arbitrary-read nor arbitrary-write primitive.
v1.0.0 underwent a full security-focused code review (plans/20261117-difflens/reports/code-review-v1.0.0.md on main): module-by-module read of the whole security surface, traced end-to-end.
- P0 findings: 0. The checksum-before-rename ordering, archive gates, manifest validation, loopback guard and HTML escaping were verified correct and adversarially tested.
-
5 P1 + 10 P2 findings were filed; the v1.0.1 release fixes them all: API key off argv, loopback guard literal-only, bounded 416 resume / 256 KiB stream cap / 50-job pruning, lock-poisoning errors instead of panics, owner-only OCR temp files, high-entropy session keys, working download cancel, path validation for
run_diff/export_report,spawn_blockingpipeline, and SHA-pinned GitHub Actions. - The review also recorded thirteen "verified-good" invariants (checksum ordering, archive gates, loopback guard, SSE parser robustness, alignment determinism, parameterized SQL, subprocess hygiene, strict CSP with zero
dangerouslySetInnerHTML, and more) that future changes must not regress.
- It does not mean air-gapped: the Downloads screen does touch the network, on your explicit click, for explicitly checksummed artifacts.
- It does not mean vetted for a hostile same-user attacker: threat model is your own machine, your own account.
- It does not mean the LLM explanations are authoritative: they are generated text from a local model — see the disclaimer in How-Diffing-Works.