# Manifesto do pacote .catplug

> Estrutura do arquivo .catplug, campos do manifest.json, regras de validação, permissões, destinos, hashes SHA-256 e o formato 2.

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

## Estrutura do pacote

Um `.catplug` é um arquivo ZIP com `manifest.json` na raiz e os arquivos listados em `hashes`.

```text
auditor.catplug
├── manifest.json
├── main.js
├── fixtures.json
├── README.pt-BR.md
└── README.en.md
```

## Exemplo completo

```json
{
  "formatVersion": 1,
  "apiVersion": 1,
  "id": "lab.auditor",
  "version": "1.0.0",
  "author": "NetCatTest",
  "entry": "main.js",
  "name": {"pt-BR": "Auditor de respostas", "en": "Response auditor"},
  "description": {"pt-BR": "Audita cabeçalhos de cache.", "en": "Audits cache headers."},
  "permissions": ["traffic.read", "traffic.modify", "findings", "commands", "ui.tab"],
  "targets": ["api.aurora.test"],
  "externalHosts": [],
  "settings": {"laboratory": true},
  "hashes": {
    "main.js": "84f7f8620e4ccde480b3a929483f51a0d051c2fe89443ecd4409faea663e071b"
  }
}
```

## Campos

| Campo | Tipo | Regra |
|---|---|---|
| `formatVersion` | número | `1` ou `2` |
| `apiVersion` | número | `1` |
| `id` | texto | `[a-z][a-z0-9.-]{2,63}`, estável entre versões |
| `version` | texto | `MAIOR.MENOR.CORREÇÃO`, por exemplo `1.0.0` |
| `author` | texto | obrigatório |
| `entry` | texto | arquivo `.js` do próprio pacote, até 128 KiB |
| `name` | objeto | `pt-BR` e `en` obrigatórios |
| `description` | objeto | `pt-BR` e `en` obrigatórios |
| `permissions` | lista | capacidades conhecidas, sem repetição |
| `targets` | lista | destinos de `cat.http.send`, até 100 |
| `externalHosts` | lista | destinos de `cat.external.call`, até 100 |
| `settings` | objeto | valores iniciais lidos por `cat.settings.get` |
| `settingsSchema` | objeto | opcional, até 32 campos |
| `hashes` | objeto | SHA-256 de cada arquivo, exceto o manifesto |

> [!IMPORTANTE]
> Nomes, descrições e textos de interface precisam ter `pt-BR` e `en`. IDs e comandos são estáveis nos dois idiomas. Sem as duas traduções o pacote é recusado com `E_TRANSLATION`.

## Permissões

| Capacidade | Libera |
|---|---|
| `traffic.read` | `cat.events.on` e conteúdo HTTP em menus |
| `traffic.modify` | `cat.proxy.onRequest` e `cat.proxy.onResponse` |
| `http.send` | `cat.http.send` e `cat.http.cancel` |
| `external.call` | `cat.external.call` |
| `ui.menu` | `cat.ui.menu.register` |
| `ui.tab` | `cat.ui.tab.register` e `cat.ui.update` |
| `storage` | `cat.storage` |
| `findings` | `cat.findings.add` |
| `repeater` | `cat.tools.repeater.open` |
| `commands` | `cat.commands.register` e `cat.commands.execute` |
| `pipeline.step` | `cat.pipeline.registerStep` |
| `parsers` | `cat.parsers.register` |
| `connector.run` | `cat.connectors` dentro de fluxos aprovados |

> [!NOTA]
> Menus que recebem conteúdo HTTP exigem `traffic.read`, além de `ui.menu` e `commands`. O Repetir só recebe destinos aprovados.

## Destinos

`targets` e `externalHosts` aceitam domínio em IDNA, IPv4 decimal, IPv6 entre colchetes e porta explícita, com esquema e caminho opcionais.

| Exemplo | Alcance |
|---|---|
| `api.exemplo.test` | domínio exato, HTTP ou HTTPS, qualquer porta |
| `https://api.exemplo.test` | somente HTTPS na porta 443 |
| `https://api.exemplo.test:8443` | somente HTTPS na porta 8443 |
| `https://api.exemplo.test/v1` | somente HTTPS em `/v1` e abaixo |
| `*.exemplo.test` | subdomínios de `exemplo.test`, sem incluir o próprio domínio |

São recusados credenciais na URL, `?`, `#`, `%`, espaços, curinga global, curinga em IP, caminhos com `..` e barras codificadas. Caminhos exigem esquema. Redes privadas e loopback precisam de escopo explícito, e DNS e redirecionamentos são revalidados: um domínio público não pode passar a apontar para um endereço privado.

## Hashes

Cada arquivo do pacote, exceto o manifesto, precisa de uma entrada em `hashes` com o SHA-256 dos seus bytes em hexadecimal minúsculo. A quantidade de hashes deve ser igual à quantidade de arquivos. A [IDE web](https://netcattest.com/catsuite/docs/extensoes/ide) calcula tudo automaticamente na exportação, e no [CatSuite Studio](https://netcattest.com/catsuite/docs/extensoes/vscode) o comando **CatSuite: Atualizar hashes do manifesto** faz o mesmo no VS Code.

## Configurações com settingsSchema

```json
{
  "settingsSchema": {
    "laboratory": {"title": {"pt-BR": "Modo laboratório", "en": "Laboratory mode"}, "type": "boolean"},
    "limite": {"title": {"pt-BR": "Limite", "en": "Limit"}, "type": "integer", "minimum": 1, "maximum": 50},
    "chave": {"title": {"pt-BR": "Credencial", "en": "Credential"}, "type": "credential"}
  }
}
```

Tipos aceitos: `string`, `boolean`, `integer`, `number` e `credential`. O alias `secret` significa referência a credencial, não o seu conteúdo. `enum` aceita de 1 a 50 valores e as chaves seguem `[a-zA-Z0-9_.-]{1,64}`.

## Formato 2

`formatVersion: 2` acrescenta `revisionId` e `lineageId` em UUID, `parentHash`, `requiresSdk` (de `1.0.0` a `1.4.0`), assinatura Ed25519 opcional sobre JSON canônico e proteção opcional com senha. Editar no aplicativo remove a assinatura antiga e cria uma nova revisão; exportar assina com a identidade local. Veja [Segurança, cofre e proteção de dados](https://netcattest.com/catsuite/docs/seguranca).

## Limites do pacote

| Item | Limite |
|---|---|
| Arquivo `.catplug` | 10 MiB |
| Conteúdo expandido | 40 MiB |
| Arquivos | 500 |
| `manifest.json` | 64 KiB |
| Cada arquivo | 4 MiB |
| Caminhos | relativos, até 200 caracteres, sem `/` inicial, `\`, `:` ou `..` |

Links simbólicos e arquivos duplicados são recusados com `E_PATH`.