# Operacao dos conectores recebidos

Esta pasta e operacional do servidor SISC, nao deve ir para o GitHub dos programadores.

## Politica de dois selos

Um pacote de conector so pode entrar no SISC real (`/var/www/html/sisc/siscore`) quando o pacote exato possuir os dois selos emitidos pelo servidor:

1. `selo-validacao`: emitido por `validar-recebidos` apos validar estrutura, manifesto, catalogo, formato, handler, manual, teste e ausencia de segredos reais.
2. `selo-sandbox`: emitido por `testar-sandbox` apos instalar no `testesis`, chamar a API em `dryRun` e executar a mensagem de teste em sandbox ate conclusao.

Cada selo contem o SHA256 do pacote e uma assinatura HMAC-SHA256 com chave local em:

```text
/var/www/html/gitconectores/secretos/chave-selos.key
```

Essa chave deve ficar fora do controle do programador, com permissao `0600`, e deve ter backup administrativo seguro; se ela for perdida, selos antigos deixam de validar. Se o pacote for alterado depois do selo, o SHA256 muda e o instalador real recusa.

## Estrutura

- `upload.php`: pagina web para receber pacotes `.tar.gz`, `.tgz` ou `.zip`.
- `gitconectoresrecebidos/`: pasta onde os pacotes enviados ficam armazenados; usar permissao `1777` para permitir upload sem permitir remover marcas do servidor.
- `validar-recebidos`: executavel C que valida pacotes recebidos e emite `selo-validacao`.
- `validar-recebidos.c`: fonte C do validador.
- `testar-sandbox`: executavel C que instala no `testesis`, executa dry-run + sandbox e emite `selo-sandbox`.
- `testar-sandbox.c`: fonte C do testador sandbox.
- `instalar-aprovados`: executavel C que instala no SISC os pacotes com selos validos.
- `instalar-aprovados.c`: fonte C do instalador.
- `conectores-operacional.h`: funcoes C compartilhadas pelos programas.
- `backups/`: criada automaticamente antes de sobrescrever arquivos no SISC.
- `tmp/`: area temporaria de extracao.

## Compilacao dos programas C

Se precisar recompilar:

```bash
cd /var/www/html/gitconectores
gcc -std=c11 -O2 validar-recebidos.c -o validar-recebidos
gcc -std=c11 -O2 instalar-aprovados.c -o instalar-aprovados
gcc -std=c11 -O2 testar-sandbox.c -o testar-sandbox
chmod +x validar-recebidos instalar-aprovados testar-sandbox
chmod 1777 gitconectoresrecebidos
```

Nao ha versao PHP destes programas operacionais. A unica pagina PHP mantida aqui e `upload.php`, porque ela e uma pagina web de upload.

## Upload autenticado e homologação de programador

A página `upload.php` agora aceita `login`, `token`, `modo` e `pacote`.

- `modo=teste`: autentica em `testesis/token-externo/<login>.txt`, recebe o pacote e instala/sobrescreve somente em `/var/www/html/sisc/testesis` usando `instalar-aprovados --homologacao-sem-selo --forcar`. Esse modo é para o programador consumir e corrigir antes da aprovação; não emite selo final e nunca instala no `siscore`.
- `modo=aprovacao`: autentica com o mesmo login/token de teste, roda `validar-recebidos --revalidar`, `testar-sandbox --retestar` e `instalar-aprovados --forcar`. Só integra ao `siscore` se os selos oficiais conferirem.

A autenticação do upload usa somente tokens cadastrados no `testesis`; não cadastre token de programador no `siscore` real.

Permissões recomendadas para processamento síncrono via servidor web: conceder ao usuário do webserver acesso de leitura a `testesis/token-externo`, escrita controlada em `gitconectoresrecebidos/`, `tmp/`, `backups/` e nas áreas de homologação `testesis/conectores` e `testesis/web-api`. A chave `secretos/chave-selos.key` continua sendo necessária para o modo aprovação; em produção prefira grupo restrito do serviço/worker em vez de permissão pública.

## Validar recebidos

```bash
cd /var/www/html/gitconectores
./validar-recebidos
```

Para revalidar pacotes que ja possuem marca/selo:

```bash
./validar-recebidos --revalidar
```

Para validar um pacote especifico:

```bash
./validar-recebidos --pacote=/var/www/html/gitconectores/gitconectoresrecebidos/pacote.tar.gz
```

Marcas geradas ao lado do pacote:

- `<pacote>.aprovado.json`
- `<pacote>.reprovado.json`
- `<pacote>.selo-validacao.json`

## Testar no sandbox

O sandbox automatico exige declaracao explicita no manifesto do conector:

```json
"testeSandbox": {
  "permitido": true,
  "semEfeitoReal": true,
  "descricao": "explicar por que a mensagem de teste nao causa efeito real"
}
```

Executar:

```bash
cd /var/www/html/gitconectores
./testar-sandbox
```

Pacote especifico:

```bash
./testar-sandbox --pacote=/var/www/html/gitconectores/gitconectoresrecebidos/pacote.tar.gz
```

Repetir teste mesmo quando ja existe selo sandbox valido:

```bash
./testar-sandbox --retestar --pacote=/var/www/html/gitconectores/gitconectoresrecebidos/pacote.tar.gz
```

Marcas geradas:

- `<pacote>.selo-sandbox.json`
- `<pacote>.falha-sandbox.json`

Credenciais da API de sandbox podem vir de `SISC_SANDBOX_API_URL`/`SISC_SANDBOX_API_TOKEN` ou de `testesis/token-externo/*.txt`.

Guarda de conformidade: `testar-sandbox` recusa executar quando `SISC_SANDBOX_DESATIVADO` estiver definido e faz preflight do destino, exigindo `escuta/sandbox-handler` executável e `escuta/runtime-conector` compilado com as marcas do sandbox novo.

## Instalar aprovados no SISC

Simulacao segura do destino real, ja exigindo os dois selos:

```bash
./instalar-aprovados --dry-run
```

Instalacao real no destino padrao `/var/www/html/sisc/siscore`:

```bash
./instalar-aprovados
```

Destino alternativo, por exemplo sandbox, exige somente `selo-validacao`. Para homologação de programador antes do selo, use explicitamente `--homologacao-sem-selo`, sempre com destino alternativo/testesis:

```bash
./instalar-aprovados --destino=/var/www/html/sisc/testesis --forcar
./instalar-aprovados --homologacao-sem-selo --destino=/var/www/html/sisc/testesis --forcar --pacote=/caminho/pacote.tar.gz
```

Marcas geradas:

- `<pacote>.instalado.json` para o SISC real;
- `<pacote>.instalado-testesis.json` para o ambiente `testesis`;
- `<pacote>.falha-instalacao.json` em falha.

## Regras da instalacao

O instalador:

1. recusa o SISC real sem `selo-validacao` e `selo-sandbox` validos;
2. confere assinatura HMAC e SHA256 dos selos contra o pacote atual;
3. revalida o pacote antes de instalar;
4. le `dependencias.arquivos` do manifesto do conector;
5. copia arquivos declarados a partir do pacote; no kit o catálogo pode vir de `siscconectores/web-api/`, mas no destino final ele é instalado em `web-api/`;
6. nunca copia `secretos/`;
7. cria backup antes de sobrescrever arquivos;
8. atualiza `web-api/catalogo-mensagens.json` apos instalar catalogos modulares;
9. normaliza permissões dos arquivos instalados: diretórios `2775`, handler `0755`, demais arquivos `0664`, com dono/grupo `www-data:www-data` quando executado como `root`;
10. normaliza marcas geradas ao lado do pacote para o mesmo dono/grupo do pacote, evitando arquivos operacionais presos ao usuário `root`;
11. quando a instalação aprovada entra no `siscore` real, remove completamente o mesmo conector do `testesis`: diretório do conector, catálogo modular, segredo/sample eventual, arquivos do espaço e qualquer arquivo/diretório fora de `.git` cujo nome ou conteúdo ainda referencie o conector; em seguida regenera o catálogo agregado do `testesis`.