Skip to content

Privacy and Security

vibecoder880 edited this page Nov 19, 2026 · 1 revision

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.

The threat model

  • 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.

Zero runtime egress

  • 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 by scripts/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 (even localhost) 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_KEY environment variable, never the command line, so it cannot be read from the process table.

Download integrity chain

Every artifact the Downloads manager fetches passes this chain:

  1. 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 flagged verified: false are fatal for primaries and server assets, so a tampered shipped manifest cannot disable checksumming.
  2. HTTPS fetch into a .part file, with size caps enforced up-front (Content-Length vs manifest bytes) and while streaming.
  3. SHA-256 verification on the .part file — before any rename — against the manifest checksum. Mismatch ⇒ part file deleted; nothing becomes "installed".
  4. Atomic rename into place. Interrupted transfers resume from the .part; Cancel genuinely aborts (v1.0.1 fix) while keeping the part for resume.

Archive extraction gates

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.

Report escaping

Exported HTML/Markdown reports embed document-derived text, so escaping is golden-tested against hostile content:

  • html_escape covers & < > " ' 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.

The review process

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_blocking pipeline, 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.

What "local-first" does not mean

  • 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.

Clone this wiki locally