SOWA Privacy para programadores

Instalar a partir do código-fonte

SOWA Privacy é distribuído pela Chrome Web Store como binário, mas o código-fonte está disponível para inspeção e uso pessoal sob a licença Source-Available em LICENSE. Para compilar e carregar localmente:

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

De seguida abra chrome://extensions/, ative o Modo de programador e clique em Carregar sem compactar sobre a pasta dist/.

Três pacotes de fornecedores volumosos

Compilados uma vez com esbuild antes de o Vite ser executado, tornando o build de produção totalmente autocontido:

• web-llm.bundle.js – ~5,4 MB – inferência de LLM local (opcional, ativação manual).
• transformers.bundle.js + onnx-wasm/* – ~32 MB – runtime do pipeline NER (opcional, ativação manual).
• file-parsers.bundle.js + pdf.worker.min.mjs + xlsx-worker.bundle.js – ~2 MB – análise de PDF, DOCX, XLSX para o intercetor de carregamento de ficheiros.

O que está incluído

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 – keep green
scripts/                      esbuild bundle + zip packaging

Garantias de privacidade

Estas são as regras aplicadas no código, não apenas promessas em material de marketing:

• Sem telemetria, sem análises, sem chamadas ao servidor próprio – com uma única exceção de âmbito restrito: a verificação do direito de acesso do utilizador (um único POST autenticado a /api/entitlements/me que apenas devolve os indicadores de plano do utilizador). Em cache por uma hora. Sem DPI, sem prompts.
• NER desativado por defeito, ativação manual – the NER model is a 65 MB third-party download (HuggingFace). It never starts loading until the user explicitly checks the toggle in Settings.
• LLM local desativado por defeito, ativação manual – mesma regra. Os modelos WebLLM são volumosos; a decisão de transferir um cabe ao utilizador.
• O Owl tem âmbito por site – o script de conteúdo regista-se em <all_urls> para os hooks de ciclo de vida, mas a deteção, o pré-aquecimento do modelo e o widget owl apenas são executados nos sete hosts em contentIntegration.entries (ChatGPT, OpenAI, Claude, Gemini, Copilot, Grok, x.ai).
• A CSP proíbe a execução dinâmica de código – 'wasm-unsafe-eval' para ONNX é permitido; 'unsafe-eval' não. Sem Function-from-string, sem plugins baseados em eval.
• Apenas Promises para as APIs chrome.* – sem formato de callback que obscureça o tratamento de erros.
• Service worker sem estado – o MV3 termina de forma agressiva; a persistência reside em chrome.storage, não em variáveis globais de módulo.

Testes

Os testes são a principal barreira de correção. A partir da v1.2.5.x: 688 de 689 a passar em 17 suites. O novo código deve mantê-los verdes.

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

As correções de bugs seguem o formato TDD: primeiro escreva o teste que falha, corrija o bug e o teste permanece como proteção contra regressões. Exemplo real incluído em tests/unit/lib/ner-detector.test.js – o teste "detect-counter does NOT reset on subsequent init successes" foi escrito antes da correção correspondente e apanhou uma primeira tentativa de implementação incorreta.

Contribuir

As contribuições para o repositório oficial são bem-vindas nos termos da licença. Abra um problema ou submeta um pull request seguindo os padrões de engenharia em CONTRIBUTING.md:

• Crie um branch a partir de main. Uma alteração lógica por PR.
• Convenção de mensagens de commit: type(scope): description (vX.Y.Z.W).
• Atualize o MIGRATION_LOG.md para alterações não triviais (novos módulos, alterações de contrato, mudanças arquiteturais).
• Lista de verificação antes de submissão para PRs que toquem em deteção ou rede: sem novo fetch() a um servidor próprio, sem nova telemetria, sem componente pesado ativado automaticamente, qualquer coisa armazenada vai para o registo de migração, qualquer nova permissão deve ser justificada para o revisor da Chrome Web Store.

Divulgação responsável

Para vulnerabilidades de segurança, por favor não abra problemas públicos no GitHub. Envie um relatório detalhado para security@sowaprivacy.ai:

• Descrição clara da vulnerabilidade.
• Passos para reproduzir.
• Versão afetada (o campo version em manifest.json).
• Avaliação de impacto, se disponível.
• Correção sugerida, se aplicável.

Comprometemo-nos a acusar a receção do seu relatório em 72 horas, a fornecer uma atualização de estado em 7 dias, a reconhecê-lo nas notas de versão (salvo preferência de anonimato) e a coordinar consigo o momento da divulgação pública.

O âmbito publicado, exemplos do que consideramos uma vulnerabilidade e um Hall of Fame encontram-se em SECURITY.md na raiz do repositório.