{"id":14008599,"url":"https://github.com/gbaptista/luminous","last_synced_at":"2025-08-03T04:32:57.229Z","repository":{"id":149073598,"uuid":"118333388","full_name":"gbaptista/luminous","owner":"gbaptista","description":"Identify, analyze and block code execution and event collection through JavaScript in your browser with code interception.","archived":false,"fork":false,"pushed_at":"2020-02-04T21:11:32.000Z","size":39585,"stargazers_count":97,"open_issues_count":22,"forks_count":11,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-06-01T12:10:35.927Z","etag":null,"topics":["chrome","chromium","debugger","firefox","freedom","interceptor","javascript","monitor","opera","performance","privacy","webextension"],"latest_commit_sha":null,"homepage":"https://gbaptista.github.io/luminous","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gbaptista.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-01-21T12:37:43.000Z","updated_at":"2024-12-18T05:07:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"dccba7cc-5c0a-4775-9571-2befe80835bd","html_url":"https://github.com/gbaptista/luminous","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/gbaptista/luminous","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbaptista%2Fluminous","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbaptista%2Fluminous/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbaptista%2Fluminous/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbaptista%2Fluminous/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gbaptista","download_url":"https://codeload.github.com/gbaptista/luminous/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbaptista%2Fluminous/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268495882,"owners_count":24259397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chrome","chromium","debugger","firefox","freedom","interceptor","javascript","monitor","opera","performance","privacy","webextension"],"created_at":"2024-08-10T11:01:54.046Z","updated_at":"2025-08-03T04:32:55.406Z","avatar_url":"https://github.com/gbaptista.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Luminous: Bloqueador de eventos JavaScript ![Icon](images/icons/48.png)\n\n\u003e [en-US](doc/en-US) | [es](doc/es) | pt-BR\n\nUma extensão experimental para identificar, analisar e bloquear a execução de códigos e a coleta de eventos via *JavaScript* em seu navegador.\n\n- [Por quê?](#por-qu%C3%AA)\n- [Entendendo a interface do usuário](#entendendo-a-interface-do-usu%C3%A1rio)\n- [Como instalar](#como-instalar)\n- [Experimente!](#experimente)\n- [Capturas de tela](#capturas-de-tela)\n- [Se aprofunde no tema](#se-aprofunde-no-tema)\n- [Guias](#guias)\n- [Como colaborar](#como-colaborar)\n- [Problemas conhecidos](#problemas-conhecidos)\n- [Entendendo o código](#entendendo-o-c%C3%B3digo)\n- [Licença](#licen%C3%A7a)\n- [Doações](#doa%C3%A7%C3%B5es)\n\n## Por quê?\n\nExistem projetos incríveis como o [*Lightbeam*](https://www.mozilla.org/pt-BR/lightbeam/), [*NoScript*](https://noscript.net/), [*ScriptSafe*](https://github.com/andryou/scriptsafe), [*uBlock Origin*](https://github.com/gorhill/uBlock), [*HTTPS Everywhere*](https://github.com/EFForg/https-everywhere) e diversos outros. Todos possuem a proposta de identificar e/ou impedir a execução de códigos e requisições questionáveis.\n\nTais ferramentas são vitais, mas inevitavelmente precisamos fazer concessões para conseguir acessar muitos sites já que a utilização de *JavaScript* é massiva na web. Ao acessar por exemplo o [*Google Tradutor*](https://translate.google.com), utilizando um combo de 3 extensões (*HTTPS Everywhere*, *uBlock Origin* e *ScriptSafe*) com a *Luminous* temos o seguinte resultado após um breve momento de utilização do website:\n\n\u003e ![Icon](images/doc/global/google-translator.jpg)\n\n- **6** requisições influenciadas pela *HTTPS Everywhere*\n- **75** requisições bloqueadas pela *uBlock Origin*\n- **4** itens bloqueados pela *ScriptSafe*\n- **7,6 mil** execuções de *JavaScript* detectadas pela *Luminous*\n\nÉ sobre este número (**7,6 mil**) que estamos perdidos e de mãos atadas, é alí que não sabemos o que acontece e ainda não temos a liberdade de decidir o que pode e o que não pode ser executado. Este é o principal objetivo do projeto, preencher esta lacuna e conseguir ver e controlar o que acontece. Como efeito colateral acabamos tendo também uma ferramenta interessante que ajuda no desenvolvimento de códigos em *JavaScript* ao nos dar visibilidade sobre o que está acontecendo.\n\n## Entendendo a interface do usuário\n\n![Interface Overview](images/doc/pt-BR/interface-overview.png)\n\n## Como instalar\n\n- Chromium e Google Chorme: [Chrome Web Store](https://chrome.google.com/webstore/detail/luminous-javascript-event/baacpbikplogpeecclpnajnlghmcldkb)\n- Mozilla Firefox: [Fifrefox Add-ons](https://addons.mozilla.org/pt-BR/firefox/addon/luminous/)\n- Opera: [Complementos do Opera](https://addons.opera.com/pt-br/extensions/details/luminous-javascript-events-blocker/)\n\n## Experimente!\n\n[Instale](#como-instalar) a extensão e acesse a nossa [página de demonstração](https://gbaptista.github.io/luminous/html/demos/detections/index.html) para experimentar e entender melhor o seu funcionamento:\n![Demo Page](images/doc/pt-BR/demo-page.png)\n\n## Capturas de tela\n\nVeja algumas capturas de tela [aqui](./doc/pt-BR/guides/screenshots.md).\n\n## Se aprofunde no tema\n\n- Documentário: [*Do Not Track*](https://donottrack-doc.com)\n- Livro: [*1984*](https://www.amazon.com.br/1984-George-Orwell-ebook/dp/B009XE662U)\n- Livro: [*Cypherpunks. Liberdade e o Futuro da Internet*](https://www.amazon.com.br/Cypherpunks-Liberdade-internet-Julian-Assange-ebook/dp/B018SLCLPO)\n- Livro: [*O filtro invisível: O que a internet está escondendo de você*](https://www.amazon.com.br/filtro-invisível-internet-está-escondendo-ebook/dp/B008OHONOU)\n- Página na web: [*A Armadilha do JavaScript*](https://www.gnu.org/philosophy/javascript-trap.pt-br.html)\n- Página na web: [*Saúde da Internet*](https://www.mozilla.org/pt-BR/internet-health/)  \n- Página na web: [*Sobre o Lightbeam*](https://www.mozilla.org/pt-BR/lightbeam/about)\n\n## Guias\n\nGuias são documentos sobre assuntos muitos específicos onde podemos ir fundo nos detalhes e encontrar facilmente as informações que estamos procurando. Veja [aqui](./doc/pt-BR/guides/) todos os guias.\n\n## Como colaborar\n\n  - [Espalhe a ideia](#espalhe-a-ideia)\n    - [Escreva algum guia](#escreva-algum-guia)\n    - [Compartilhe](#compartilhe)\n    - [Escreva e fale sobre](#escreva-e-fale-sobre)\n    - [Ajude na tradução para outros idiomas](#ajude-na-tradu%C3%A7%C3%A3o-para-outros-idiomas)\n  - [Reporte problemas](#reporte-problemas)\n    - [Problemas em sites específicos](#problemas-em-sites-espec%C3%ADficos)\n    - [Problemas em algum navegador](#problemas-em-algum-navegador)\n  - [Bote a mão na massa](#bote-a-m%C3%A3o-na-massa)\n    - [Ajude a melhorar a interface do usuário](#ajude-a-melhorar-a-interface-do-usu%C3%A1rio)\n    - [Melhore o desempenho](#melhore-o-desempenho)\n    - [Crie novas funcionalidades](#crie-novas-funcionalidades)\n    - [Melhore a qualidade do código](#melhore-a-qualidade-do-c%C3%B3digo)\n\n### Espalhe a ideia\n\n#### Escreva algum guia\n\nColabore escrevendo algum [guia](#guias) sobre assuntos relacionados ao projeto.\n\n#### Compartilhe\n\nConte aos seus amigos, familiares e colegas de trabalho sobre como a extensão foi utilizada para melhorar a sua experiência na web e os ensine a utilizá-la também!\n\n#### Escreva e fale sobre\n\nDescobriu que algum site estava invadindo a sua privacidade? Conseguiu bloquear eventos que não desejava? Conseguiu facilitar o desenvolvimento do seu código ou a depuração de erros? Grave um video, prepare uma palestra, escreva um artigo ou qualquer coisa do gênero contando como foi feito, explicando como a extensão o ajudou e mostrando as possibilidades.\n\n#### Ajude na tradução para outros idiomas\n\nTraduza os arquivos `.md` encontrados dentro do diretório `doc/` e os arquivos `.json` dentro do diretório `_locales/` para o seu idioma e nos ajude a atingir mais pessoas!\n\n### Reporte problemas\n\n#### Problemas em sites específicos\n\nTeve problemas ao acessar algum site por causa da extensão? Ficou lento? Causou erros? O site parou de funcionar? Nem todos os eventos foram identificados? Abra uma [*issue*](https://github.com/gbaptista/luminous/issues) e conte pra gente sobre o que aconteceu.\n\n#### Problemas em algum navegador\n\nAbra uma [*issue*](https://github.com/gbaptista/luminous/issues) se algo não funcionou como você esperava em algum navegador. Queremos que tudo funcione bem em todos os navegadores possíveis!\n\n### Bote a mão na massa\n\n#### Ajude a melhorar a interface do usuário\n\nNão temos a interface mais bonita e amigável possível. [Discussões](https://github.com/gbaptista/luminous/issues) e [propostas](https://github.com/gbaptista/luminous/pulls) sobre uma nova interface ou melhorias na já existente (*`html/interface-sample.html`*) serão muito bem-vindas! Não subestime o poder desse tipo de colaboração: [better_errors#6](https://github.com/charliesome/better_errors/issues/6) - [better_errors#22](https://github.com/charliesome/better_errors/pull/22)\n\n#### Melhore o desempenho\n\n**Exemplo 1**: Quanto mais cedo conseguirmos injetar o código nos websites e quanto menos recursos utilizarmos para processar as informações, mais execuções seremos capazes de identificar e melhor será a nossa experiência ao ter uma extensão que não deixe a navegação lenta.\n\nOlhe por exemplo para a nossa página de demonstração (*`html/demos/detections/index.html`*):\n\n```javascript\n(function() { setTimeout(function() {\n  // JavaScript code...\n}, 100); })();\n```\n\nEsse delay de 100 milessegundos existe pois sem ele o código é executado rápido demais e não conseguimos interceptá-lo. Como podemos melhorar isso para não precisarmos desse delay ou então conseguir diminuí-lo?\n\n\n**Exemplo 2**: Capturamos apenas um pedaço da função interceptada, pois ela pode ser muito grande e deixar a leitura das informações lenta (*`js/content/interceptor.js`*):\n\n```javascript\nlistener: ('' + listener).slice(0, 400)\n```\n\nComo podemos melhorar isso? Essa é a melhor maneira de lidar com este problema?\n\n**Exemplo 3**: A maneira que encontramos de passar mensagens do contexto do documento para o contexto da extensão foi realizando o *parser* dos dados em *JSON* lendo um elemento *HTML* (*`js/content/readers/data.js`*):\n\n```javascript\nrender_data(\n  JSON.parse($(data_element).html()),\n  tab_id\n);\n```\nExistem alternativas? Fazer o *parse* das informações constantemente é a melhor opção?\n\n#### Crie novas funcionalidades\n\nComeçamos com uma ideia básica: identificar e bloquear eventos. Podemos expandir essa ideia, alguns pensamentos que já surgiram:\n\n- Interceptamos apenas chamadas para o `addEventListener` e o `handleEvent`. Não seria interessante interceptarmos também chamadas para o `XMLHttpRequest` e outros?\n\n\n- Não estamos interceptando eventos definidos *inline* (`\u003ca onclick=\"someAction()\"\u003e`), não seria interessante fazer isso?\n\n\n- Hoje podemos bloquear os eventos por domínio: *\"Bloquear a execução de `mouseover` no domínio `somesite.com`\"*. Não seria interessante ter regras mais elaboradas e bloquear um evento apenas se o seu alvo for um tipo de elemento X ou o código executado for de acordo com alguma expressão regular?\n\n#### Melhore a qualidade do código\n\nEste é um projeto experimental que cresceu de forma descontrolada, não temos um padrão definido de nomenclatura, uma forte organização baseada em algum *design pattern* ou testes automatizados. Discussões para melhorar a qualidade do código nesse sentido serão muito bem-vindas!\n\n## Problemas conhecidos\n\n - [Sem soluções alternativas](#sem-solu%C3%A7%C3%B5es-alternativas)\n - [Com soluções alternativas](#com-solu%C3%A7%C3%B5es-alternativas)\n   - [Service Workers no Mozilla Firefox](#service-workers-no-mozilla-firefox)\n\n### Sem soluções alternativas\n - Não interceptamos codigos *inline* (`\u003ca onclick=\"someAction()\"\u003e`).\n\n\n - Um código pode ser executado antes de conseguirmos injetar o interceptador. É raro, mas possível.\n\n\n - Alguns sites com uma quantidade absurda de eventos *JavaScript* pode deixar o navegador lento por conta da coleta de dados sobre as interceptações realizadas.\n\n### Com soluções alternativas\n\n#### Service Workers no Mozilla Firefox\n\nNo *Mozilla Firefox* e derivados, alguns sites que utlizam [*Service Workers*](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) (como o [*WhatsApp Web*](https://web.whatsapp.com/)) podem bloquear o código de interceptação por conta de um *bug* na interceptação dos *headers* com as diretrizes de [*Content-Security-Policy*](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy). A solução alternativa atual consiste em recarregar o *Service Worker*:\n\n - Acesse a tela de *Service Workers* em: `about:debugging#workers`\n - Clique em *unregister* no *Service Worker* do site desejado:\n\n  ![Service Workers](images/doc/global/firefox-service-workers.jpg)\n - Recarregue o site.\n\n## Entendendo o código\n\n- [Background](#background)\n- [Content](#content)\n- [Pop-up](#pop-up)\n- [Configurações](#configurações)\n- [Utilidades](#utilidades)\n- [Bibliotecas de terceiros](#bibliotecas-de-terceiros)\n\n### Background\n\n`js/background`:\n\n- `js/background/set_current_tab.js`: Responsável por injetar o *ID* da *tab* atual no documento.\n\n- `js/background/set_response_headers.js`: Responsável por alterar o *header* de *Content-Security-Policy* das requisições.\n\n- `js/background/update_badge.js`: Responsável por atualizar o contador mostrado no ícone da extensão.\n\n### Content\n\n`/content/injections`:\n\n - `/content/injections/data.js`: Responsável por injetar o elemento *HTML* que armazenará os dados coletados das interceptações.\n\n - `/content/injections/interceptor.js`: Responsável por injetar o código que executará as interceptações de fato no documento.\n\n- `/content/injections/options.js`: Responsável por injetar o elemento *HTML* que armazenará os opções definidas pelo usuário.\n\n`/content/readers`:\n\n- `/content/readers/data.js`: Responsável por ler os dados no elemento *HTML* do documento que armazena os detalhes coletados das interceptações e repassa-los à extensão.\n\n`/content/injections_controller.js`: Responsável por tomar decisões sobre a injeção de códigos.\n\n`/content/interceptor.js`: Responsável por interceptar execuções de códigos *JavaScript* no contexto do documento e coletar detalhes sobre elas.\n\n### Pop-up\n\nResponsáveis por renderizar e cuidar das interações feitas no pop-up que é aberto ao clicar no ícone da extensão:\n\n- `html/popup/popup.html`\n- `html/popup/templates/counters.html`\n- `html/popup/templates/options.html`\n- `js/popup/popup.js`\n- `css/popup/popup.css`\n\n### Configurações\n\nResponsáveis por renderizar e cuidar das interações feitas nas páginas de configurações:\n\n- `html/settings/*.html`\n- `js/settings/*.js`\n- `css/settings/*.css`\n\n### Utilidades\n\n- `js/utils/colors.js`: Função utilizada para determinar a cor exibida com base no valor do contador.\n- `js/utils/number.js`: Função utilizada para formatar o número de acordo com seu tamanho.\n\n### Bibliotecas de terceiros\n\n- `vendor/bootstrap`: [*Bootstrap: biblioteca de componentes front-end\n*](https://github.com/twbs/bootstrap)\n- `vendor/jquery`: [*jQuery JavaScript Library*](https://github.com/jquery/jquery)\n- `vendor/mustachejs`: [*Minimal templating with {{mustaches}} in JavaScript*](https://github.com/janl/mustache.js)\n- `vendor/tippyjs`: [*A lightweight, vanilla JS tooltip library*](https://github.com/atomiks/tippyjs)\n\n## Licença\n\nEste projeto está licenciado sob a [*GPLv3*](LICENSE).\n\n## Doações\n\nNão há nenhum tipo de organização para o recebimento de doações no momento. Veja nosso guia sobre *\"[como colaborar](#como-colaborar)\"* para outras maneiras de contribuição. Se deseja realmente realizar uma doação, eis algumas fundações incríveis que vão de encontro com os temas abordados neste projeto que você pode ajudar:\n\n- [*Electronic Frontier Foundation*](https://supporters.eff.org/donate)\n- [*Free Software Foundation*](https://www.fsf.org/about/ways-to-donate)\n- [*Mozilla Foundation*](https://donate.mozilla.org)\n- [*Tor Project*](https://donate.torproject.org)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbaptista%2Fluminous","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgbaptista%2Fluminous","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbaptista%2Fluminous/lists"}