# Certificados Digitais

## Regra principal

Na versao final, certificado e senha ficam no banco novo, mas criptografados.

```text
Banco:
  certificado A1 .pfx criptografado
  senha do .pfx criptografada
  metadados do certificado

Fora do banco:
  NFSE_MASTER_KEY
```

A chave mestra usada para descriptografar esses dados nunca deve ficar no mesmo banco.

## Modelo final

A tabela `nfse_certificados` guarda:

- municipio vinculado;
- tipo de certificado (`A1_PFX`);
- `storage_tipo`, normalmente `db_encrypted`;
- certificado `.pfx` criptografado em `certificado_criptografado`;
- algoritmo e chave do certificado (`certificado_crypto_alg`, `certificado_key_id`);
- hash do PFX original (`certificado_sha256`);
- nome original do arquivo;
- senha criptografada em `senha_criptografada`;
- algoritmo e chave da senha (`senha_crypto_alg`, `senha_key_id`);
- sujeito, CNPJ/CPF, validade e status.

O campo `arquivo_path` existe apenas para desenvolvimento, migracao ou emergencia. O padrao de producao deve ser guardar o PFX criptografado no banco.

## Como o motor escolhe o certificado

O motor nao escolhe o certificado "no chute". Ele consulta o banco:

```text
nfse_municipios.codigo_ibge -> nfse_certificados
```

Fluxo:

```text
1. busca municipio ativo;
2. busca certificado ativo vinculado ao municipio;
3. garante que existem as tabelas fisicas do codigo IBGE;
4. descriptografa PFX e senha em memoria usando NFSE_MASTER_KEY;
5. abre o certificado;
6. consulta ADN;
7. grava nas tabelas do municipio.
```

## Certificado por municipio

Para operacao por municipio no ADN, o certificado esperado e o certificado da prefeitura/municipio conveniado/autorizado para aquele ambiente. Certificado de fiscal pessoa fisica nao deve ser assumido como suficiente sem confirmacao formal de delegacao/autorizacao no ambiente da NFS-e Nacional.

## Chave mestra

Exemplo:

```text
NFSE_MASTER_KEY=base64-de-32-bytes
```

Importante: se alguem tiver acesso ao banco e tambem a chave mestra, consegue recuperar certificados e senhas. Por isso a chave mestra deve ter controle de acesso separado.

## Smoke test manual

Enquanto nao houver rotina final de cadastro criptografado, o smoke test manual ainda usa arquivo local:

```sh
PFX_PASSWORD='senha' ./scripts/test_certificado_homolog.sh certificados/pinhal.pfx
```

No worker final, o arquivo nao precisa existir em disco: ele sera recuperado do banco, descriptografado em memoria e usado na chamada mTLS.

## Referencia

Detalhamento da decisao final: `docs/decisao-final-certificados.md`.