# Extensões do CatSuite

> Como funcionam as extensões .catplug: motor QuickJS isolado, permissões, ciclo de vida, pontos de integração e limites da API v1.

- Idioma: pt-BR
- URL canônica: https://netcattest.com/catsuite/docs/extensoes
- Seção: Extensões
- Atualizado: 2026-10-06
- Outro idioma (en): https://netcattest.com/catsuite/en/docs/extensions

Extensões são pacotes `.catplug` com código JavaScript executado pelo **QuickJS 2026-06-04**, incorporado por JNI em um serviço Android isolado. Cada extensão tem seu próprio ambiente, seus dados em SQLite e suas permissões.

## O que uma extensão pode fazer

- Observar requests e responses com `cat.events.on`.
- Alterar mensagens antes do encaminhamento com `cat.proxy.onRequest` e `cat.proxy.onResponse`.
- Enviar requests para destinos declarados com `cat.http.send`.
- Consultar APIs externas com credenciais protegidas com `cat.external.call`.
- Registrar comandos, menus de mensagem e abas nativas.
- Salvar dados e registrar achados com evidência.
- Participar de [fluxos visuais](https://netcattest.com/catsuite/docs/fluxos) como etapas e parsers.

## O que uma extensão não pode fazer

Não há Node.js, DOM, `fetch`, acesso geral a arquivos ou execução de processos. Use `cat.http.parseUrl` para URLs e `cat.bytes` para converter UTF-8. TLS usa a validação de certificados do Android e o SDK não pode desativá-la.

## Pontos de integração

Os hooks cobrem o proxy, o Proxy de Rede, o Repetir, o Intruso e o Descobridor. Toda mensagem informa sua origem em `source`:

| `source` | Origem |
|---|---|
| `proxy` | Tráfego do navegador interceptado |
| `network_proxy` | Sessão do Proxy de Rede |
| `repetir` | Envios do Repetir |
| `intruso` | Envios do Intruso |
| `descobridor` | Envios do Descobridor |
| `extension` | Requests enviadas por extensões |
| `laboratory` | Tráfego simulado do laboratório |

Requests de uma extensão não voltam aos próprios handlers; outras extensões podem processá-las conforme o escopo. Quando extensões processam o tráfego do proxy, as regras de substituição aplicáveis são executadas antes dos handlers, e a edição manual prevalece.

## Ciclo de vida

1. **Criar ou importar** — em **Configurações → Extensões**, use o botão Criar (modelo básico ou exemplo Aurora), importe um `.catplug` ou crie o pacote na [IDE web](https://netcattest.com/catsuite/docs/extensoes/ide) ou no [CatSuite Studio para VS Code](https://netcattest.com/catsuite/docs/extensoes/vscode).
2. **Validar** — pacote, manifesto e código são validados antes de qualquer troca.
3. **Aprovar** — instalações começam desativadas. Ao ativar, você revisa capacidades e destinos.
4. **Executar** — hooks, comandos, menus e abas entram em ação.
5. **Atualizar** — permissões ou destinos ampliados exigem nova aprovação.

> [!AVISO]
> Três falhas consecutivas suspendem a extensão. Desativar ou remover limpa os handlers e componentes registrados.

## Limites da API v1

| Recurso | Limite |
|---|---|
| Extensões ativas | 4 |
| Memória por ambiente | 32 MiB |
| Handler de alteração | 100 ms, síncrono |
| Chamadas HTTP simultâneas | 2 por extensão |
| Prazo HTTP total | 120 segundos |
| Resposta HTTP | até 8 MiB, com preview para o JavaScript |
| Preview editável | até 32 KiB |
| Script de entrada | até 128 KiB |
| Pacote | 10 MiB comprimido, 40 MiB expandido e 500 arquivos |
| Dados por extensão | 10 MiB, com 128 KiB por valor |

Corpos maiores, incompletos, comprimidos ou contínuos ficam somente para leitura. SSE e WebSocket preservam seu transporte, e túneis HTTPS sem descriptografia não fornecem conteúdo HTTP.

## Primeira extensão

```js
cat.commands.register('lab.ola', {'pt-BR': 'Dizer olá', en: 'Say hello'}, () => {
  cat.log({'pt-BR': 'Olá do laboratório.', en: 'Hello from the lab.'});
  return {ok: true};
});
```

Declare a permissão `commands` no [manifesto](https://netcattest.com/catsuite/docs/extensoes/manifesto) e rode o comando no simulador da [IDE de extensões](https://netcattest.com/catsuite/ide).

## Continue

- [SDK de extensões 1.4.0](https://netcattest.com/catsuite/docs/extensoes/sdk)
- [Manifesto do pacote .catplug](https://netcattest.com/catsuite/docs/extensoes/manifesto)
- [Referência da API JavaScript](https://netcattest.com/catsuite/docs/extensoes/api)
- [Interface, dados e achados](https://netcattest.com/catsuite/docs/extensoes/interface-e-dados)