SOWA Privacy per sviluppatori

Installa dal sorgente

SOWA Privacy viene distribuita tramite il Chrome Web Store come binario, ma il sorgente è aperto per ispezione e uso personale sotto la licenza Source-Available nel file LICENSE. Per compilarla e caricarla localmente:

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

Quindi apri chrome://extensions/, abilita la Modalità sviluppatore e clicca su Carica decompressa sulla cartella dist/.

Tre bundle vendor di grandi dimensioni

Compilati una sola volta con esbuild prima di Vite, così la build di produzione è completamente autonoma:

• web-llm.bundle.js – ~5.4 MB – inferenza LLM locale (opzionale, opt-in).
• transformers.bundle.js + onnx-wasm/* – ~32 MB – runtime pipeline NER (opzionale, opt-in).
• file-parsers.bundle.js + pdf.worker.min.mjs + xlsx-worker.bundle.js – ~2 MB – analisi di PDF, DOCX, XLSX per l'intercettore di upload file.

Contenuto del pacchetto

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 test unitari – mantenerli verdi
scripts/                      esbuild bundle + zip packaging

Garanzie sulla privacy

Queste sono le regole applicate nel codice, non semplici promesse di marketing:

• Nessuna telemetria, nessuna analisi, nessuna chiamata a server di prima parte – con un'unica eccezione circoscritta: il controllo dei diritti dell'utente (una singola POST autenticata a /api/entitlements/me che restituisce solo i flag del piano utente). Memorizzata nella cache per un'ora. Nessun dato personale, nessun prompt.
• NER disabilitata per impostazione predefinita, solo opt-in – il modello NER è un download di terze parti da 65 MB (HuggingFace). Non inizia mai a caricarsi finché l'utente non attiva esplicitamente l'opzione nelle Impostazioni.
• LLM locale disabilitato per impostazione predefinita, solo opt-in – stessa regola. I modelli WebLLM sono grandi; scaricarli è una decisione dell'utente.
• Owl è limitato al sito – il content script si registra su <all_urls> per i lifecycle hook, ma il rilevamento, il pre-riscaldamento del modello e il widget owl vengono eseguiti solo sui sette host in contentIntegration.entries (ChatGPT, OpenAI, Claude, Gemini, Copilot, Grok, x.ai).
• La CSP vieta l'esecuzione di codice dinamico – 'wasm-unsafe-eval' per ONNX è consentito; 'unsafe-eval' non lo è. Nessun Function da stringa, nessun plugin basato su eval.
• Solo Promise per le API chrome.* – nessun pattern a callback che oscuri la gestione degli errori.
• Service worker stateless – MV3 termina in modo aggressivo; la persistenza vive in chrome.storage, non nei globali del modulo.

Test

I test sono il principale controllo di correttezza. Alla versione v1.2.5.x: 688 di 689 superati in 17 suite. Il nuovo codice deve mantenere questo verde.

npm run test:unit:nocov   # fast loop during development (~3s)
npm run test:unit          # CI gate with coverage
npm run typecheck          # tsc --noEmit
npm run lint               # eslint

Le correzioni di bug seguono un approccio TDD: si scrive prima il test fallente, si corregge il bug e il test rimane come guardia di regressione. Un esempio reale è incluso in tests/unit/lib/ner-detector.test.js – il test "detect-counter does NOT reset on subsequent init successes" è stato scritto prima della relativa correzione e ha intercettato un primo tentativo di implementazione errato.

Contribuire

I contributi al repository ufficiale sono benvenuti secondo i termini della licenza. Apri un issue o invia una pull request seguendo gli standard di sviluppo in CONTRIBUTING.md:

• Crea un branch da main. Una modifica logica per PR.
• Convenzione per i messaggi di commit: type(scope): description (vX.Y.Z.W).
• Aggiorna MIGRATION_LOG.md per modifiche non banali (nuovi moduli, cambiamenti di contratto, modifiche architetturali).
• Checklist pre-invio per le PR che toccano il rilevamento o la rete: nessuna nuova chiamata fetch() a server di prima parte, nessuna nuova telemetria, nessun componente pesante abilitato automaticamente, tutto ciò che viene archiviato entra nel migration log, ogni nuova autorizzazione è giustificata per il revisore del Chrome Web Store.

Divulgazione responsabile

Per le vulnerabilità di sicurezza, ti chiediamo di non aprire issue pubbliche su GitHub. Invia un rapporto dettagliato a security@sowaprivacy.ai:

• Descrizione chiara della vulnerabilità.
• Passaggi per riprodurla.
• Versione interessata (il campo version in manifest.json).
• Valutazione dell'impatto, se disponibile.
• Correzione suggerita, se applicabile.

Ci impegniamo a confermare la ricezione del tuo rapporto entro 72 ore, a fornire un aggiornamento sullo stato entro 7 giorni, a riconoscerti nelle note di rilascio (salvo che tu preferisca l'anonimato) e a coordinare con te i tempi della divulgazione pubblica.

Il perimetro pubblicato, gli esempi di ciò che consideriamo una vulnerabilità e la Hall of Fame si trovano in SECURITY.md nella root del repository.