SOWA Privacy voor ontwikkelaars

Installeren vanuit broncode

SOWA Privacy wordt via de Chrome Web Store als binair bestand geleverd, maar de broncode is openbaar voor inspectie en persoonlijk gebruik onder de Source-Available licentie in LICENSE. Om het lokaal te bouwen en te laden:

git clone https://github.com/Sowa-Privacy/sowa-privacy-chrome-extension.git
cd sowa-privacy-chrome-extension
npm install
npm run build

Open vervolgens chrome://extensions/, schakel de Ontwikkelaarsmodus in en klik op Uitgepakt laden voor de map dist/.

Drie zware vendor-bundles

Eenmalig gebouwd met esbuild vóór Vite wordt uitgevoerd, zodat de productie-build volledig op zichzelf staat:

• web-llm.bundle.js – ~5.4 MB – lokale LLM-inferentie (optioneel, opt-in).
• transformers.bundle.js + onnx-wasm/* – ~32 MB – NER-pijplijn runtime (optioneel, opt-in).
• file-parsers.bundle.js + pdf.worker.min.mjs + xlsx-worker.bundle.js – ~2 MB – PDF-, DOCX- en XLSX-parsing voor de bestandsupload-interceptor.

Wat zit er in

manifest.json                 Chrome MV3 manifest (single source of truth for version)
contentScript.js              MV3 content script entrypoint
service_worker.js             MV3 service worker (stateless)
offscreen.js                  Offscreen doc for NER inference

lib/
  constants.js                DEF_CONFIG, PRESET_PATTERNS, NER_MODELS,
                              WEBLLM_MODELS, INDUSTRY_BLACKLISTS
  pii-core.js                 detectPII, mergeDetectionHits, blacklist + regex pipeline
  ner-detector.js             NER pipeline + diagnostic state surface
  ui-utils.js                 shouldUseRegex / NER / LLM helpers, theme, debounce
  ui_i18n.js                  t() + RESOURCES (4 locales) + applyI18n
  cs/
    owl-guardian.js           Owl widget Shadow DOM, continuous scan, badge counter
    upload-interceptor.js     File drag/drop / file input intercept
    host-matcher.js           contentIntegration.entries pattern matching

tests/unit/                   688 unit-tests – houd groen
scripts/                      esbuild-bundle + zip-packaging

Privacygaranties

Dit zijn de regels die in code worden gehandhaafd, niet alleen beloften in marketingtekst:

• Geen telemetrie, geen analyses, geen eigen serveraanroepen – met één strikt afgebakende uitzondering: de gebruikersrechtencontrole (een enkele geauthenticeerde POST naar /api/entitlements/me die uitsluitend de abonnementsflags van de gebruiker retourneert). Eén uur gecachet. Geen PII, geen prompts.
• NER standaard UIT, alleen opt-in – the NER model is a 65 MB third-party download (HuggingFace). It never starts loading until the user explicitly checks the toggle in Settings.
• Lokale LLM standaard UIT, alleen opt-in – dezelfde regel. WebLLM-modellen zijn groot; het downloaden ervan is de beslissing van de gebruiker.
• Owl is sitegebonden – het content-script registreert op <all_urls> voor lifecycle-hooks, maar detectie, model-voorverwarming en de owl-widget draaien alleen op de zeven hosts in contentIntegration.entries (ChatGPT, OpenAI, Claude, Gemini, Copilot, Grok, x.ai).
• CSP verbiedt dynamische code-uitvoering – 'wasm-unsafe-eval' voor ONNX is toegestaan; 'unsafe-eval' is niet toegestaan. Geen Function-from-string, geen eval-gestuurde plugins.
• Uitsluitend Promises voor chrome.*-API's – geen callback-vorm die foutafhandeling verhult.
• Stateless service worker – MV3 beëindigt agressief; persistentie leeft in chrome.storage, niet in module-globals.

Tests

Tests vormen de primaire correctheidscontrole. Vanaf v1.2.5.x: 688 van 689 geslaagd in 17 suites. Nieuwe code moet dit groen houden.

npm run test:unit:nocov   # snelle lus tijdens ontwikkeling (~3s)
npm run test:unit          # CI-poort met dekking
npm run typecheck          # tsc --noEmit
npm run lint               # eslint

Bugfixes volgen een TDD-patroon: schrijf eerst de falende test, herstel de bug, de test blijft als regressiebewaker. Echt voorbeeld geleverd in tests/unit/lib/ner-detector.test.js – de test "detect-counter does NOT reset on subsequent init successes" is geschreven vóór de bijbehorende fix en onderschepte een slechte eerste implementatiepoging.

Bijdragen

Bijdragen aan de officiële repository zijn welkom onder de licentievoorwaarden. Open een issue of dien een pull request in volgens de technische normen in CONTRIBUTING.md:

• Branch van main. Één logische wijziging per PR.
• Commit-berichtconventie: type(scope): description (vX.Y.Z.W).
• Update MIGRATION_LOG.md voor niet-triviale wijzigingen (nieuwe modules, contractwijzigingen, architecturale verschuivingen).
• Controlelijst voor indiening van PR's die detectie of netwerk raken: geen nieuwe fetch() naar een eigen server, geen nieuwe telemetrie, geen zwaar component automatisch ingeschakeld, alles wat u opslaat gaat naar het migratielogboek, elke nieuwe toestemming is gerechtvaardigd voor de Chrome Web Store-beoordelaar.

Verantwoorde openbaarmaking

Stuur voor beveiligingslekken geen openbare GitHub-issues. Stuur een gedetailleerd rapport per e-mail naar security@sowaprivacy.ai:

• Duidelijke beschrijving van het beveiligingslek.
• Stappen om te reproduceren.
• Betreffende versie (het veld version in manifest.json).
• Impactbeoordeling indien beschikbaar.
• Voorgestelde oplossing indien van toepassing.

Wij verbinden ons ertoe uw melding binnen 72 uur te bevestigen, binnen 7 dagen een statusupdate te geven, u te vermelden in de release-notities (tenzij u anonimiteit verkiest) en de timing van de publieke openbaarmaking met u af te stemmen.

Het gepubliceerde toepassingsgebied, voorbeelden van wat wij als een beveiligingslek beschouwen en een Hall of Fame staan in SECURITY.md in de root van de repository.