> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/iad/technical_documentation/technical_specifications.md).

# Especificações técnicas

## Requisitos mínimos

| Componente | Requisito                     |
| ---------- | ----------------------------- |
| SO         | Linux x86\_64 (Ubuntu 20.04+) |
| CPU        | 4 núcleos                     |
| Memória    | 4 GB RAM                      |
| Disco      | 1 GB de espaço livre          |

## Recomendado para produção

| Componente    | Recomendação              |
| ------------- | ------------------------- |
| SO            | Ubuntu 24.04 LTS          |
| CPU           | 8+ núcleos                |
| Memória       | 8 GB+ RAM                 |
| Rede          | Conexão de baixa latência |
| Armazenamento | SSD para logs             |

## Requisitos de rede

### Conectividade de saída

O serviço deve conseguir alcançar:

* Os servidores de licença da Facephi (para a validação da licença)

### Acesso ao servidor de licenças

**IPs e portas requeridos:**

| IP           | Porta | Protocolo |
| ------------ | ----- | --------- |
| 52.223.22.71 | 443   | TCP/IP    |
| 35.71.188.31 | 443   | TCP/IP    |
| 75.2.113.112 | 443   | TCP/IP    |
| 99.83.149.57 | 443   | TCP/IP    |

**URLs requeridas:**

* `https://api.cryptlex.com:443`
* `https://api.eu.cryptlex.com:443`

Configure as regras do firewall para permitir o tráfego HTTPS de saída para estes endpoints.

## Arquitetura de implantação

IAD Service opera como uma API REST sem estado que avalia payloads de captura e retorna um contrato público de Facephi:

```
Cliente → IAD Service (Port 6982)
```

* Podem ser executadas várias instâncias do serviço atrás de um balanceador de carga
* Cada instância mantém os recursos internos necessários para o processamento de capturas
* O serviço não armazena estado de sessão

## Compatibilidade da API pública

{% hint style="danger" %}
**Aviso de mudança incompatível (2.0.0)** A API REST pública exposta pela versão 2.0.0 quebra a compatibilidade com a série 1.x.x. Isso afeta o contrato de comunicação, não apenas a documentação. As integrações devem migrar as rotas dos endpoints, os nomes dos campos multipart e as regras de análise das respostas corretas.
{% endhint %}

| Área de Integração             | 1.x.x                       | 2.0.0                           |
| ------------------------------ | --------------------------- | ------------------------------- |
| Endpoint de Liveness           | `/api/v1/iad/check-capture` | `/api/v1/iad/liveness/evaluate` |
| Endpoint de extração           | `/api/v1/iad/extract-image` | `/api/v1/iad/extract`           |
| Campo da solicitação multipart | `file`                      | `capture`                       |
| Payload correto de Liveness    | Campos privados herdados    | Campos públicos de Facephi      |

## Mitigação experimental de ataques de repetição (replay)

O serviço pode aplicar uma janela de vigência (freshness window) aos payloads de captura de entrada. Essa proteção experimental está desabilitada por padrão.

* Ative-a com `FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED=true`
* Ajuste a janela de vigência com `FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME=<seconds>`
* Janela de vigência padrão: `300` segundos
* Aplica-se aos endpoints de processamento de capturas como `POST /api/v1/iad/liveness/evaluate` e `POST /api/v1/iad/extract`
* Quando a janela de vigência é excedida, a API pública retorna HTTP `400` com `message` igual a `Replay attack detected`

Essa funcionalidade é configurada na inicialização por meio de variáveis de ambiente. Não faz parte de `config.json` nem é exposta por meio de `GET|POST /api/v1/iad/config`.

## Autenticação JWT

A autenticação JWT pode ser habilitada na inicialização por meio de `config.json` ou por meio de variáveis de ambiente `FACEPHI_IAD_REST_AUTH_*`.

* Chaves de inicialização suportadas: `auth_enabled`, `auth_jwt_secret`, `auth_accept_authorization_header`, `auth_accept_api_key_header`, `auth_api_key_header_name`
* `GET /api/v1/iad/config` omite essas chaves da visualização pública de configuração
* `POST /api/v1/iad/config` rejeita essas chaves e não pode ser usado para rotacionar a configuração de autenticação JWT em tempo de execução

## Características de desempenho

| Métrica                       | Valor típico                                                                       |
| ----------------------------- | ---------------------------------------------------------------------------------- |
| Latência                      | < 100ms                                                                            |
| Desempenho (throughput)       | Depende do dimensionamento do serviço e da capacidade de processamento de capturas |
| Conexões simultâneas          | Limitadas por `number_of_threads` e `engine_pool_size`                             |
| Tamanho máximo da solicitação | Configurável por meio de `client_max_body_size`                                    |

## Considerações de segurança

* Implante por trás de um proxy reverso ou de um gateway de API (API gateway)
* Habilite SSL/TLS para todas as comunicações
* Priorize injetar `auth_jwt_secret` por meio de variáveis de ambiente ou de um gerenciador de segredos em vez de incluí-lo em arquivos
* Proteja o arquivo de licença com as permissões adequadas (chmod 644)
* Use regras de firewall para restringir as conexões de entrada

### Mensagens de erro normalizadas por Facephi

Para `POST /api/v1/iad/liveness/evaluate`, as falhas de validação de captura são normalizadas para valores públicos de `message`, incluindo:

* `NoneBecauseFaceTooClose`
* `NoneBecauseFaceNotFound`
* `NoneBecauseFaceCropped`
* `NoneBecauseFaceOccluded`
* `NoneBecauseTooManyFaces`
* `NoneBecauseAngleTooLarge`
* `NoneBecauseFaceTooSmall`
* `NoneBecauseFaceTooCloseToBorder`
* `NoneBecauseEyesClosed`
* `NoneBecauseImageDataError`
* `NoneBecauseLicenseError`
* `Replay attack detected`
* `ErrorProcessing`

Para `POST /api/v1/iad/extract`, as falhas de análise e desencriptação do payload são retornadas como `NoneBecauseImageDataError`; as capturas expiradas rejeitadas pela proteção contra repetições retornam `Replay attack detected`; as falhas de extração não classificadas são retornadas como `ErrorFacialImage`.

As respostas corretas de Liveness são mapeadas para os campos públicos `diagnostic`, `reason`, `probability`, `score`, `faceProbability` opcional, `sdkDuration` e `queueDuration`. Os campos privados herdados e os payloads brutos do engine não são expostos.

Os valores possíveis para `reason` em `POST /api/v1/iad/liveness/evaluate` são:

* `None`
* `Unknown`
* `UntrustedEnvironment`
* `SuspiciousActivity`
* `UntrustedDevice`
* `SdkIntegrityViolation`
* `UntrustedCorruptedPayload`
* `UntrustedContent`
* `UntrustedContentLowConfidence`

O significado de cada valor público de `reason` é:

| `reason`                        | Significado                                                                                                                                              |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `None`                          | A captura foi aceita como `Live` e não se aplica nenhum motivo de rejeição.                                                                              |
| `Unknown`                       | O serviço não conseguiu atribuir a resposta a um motivo de rejeição público documentado.                                                                 |
| `UntrustedEnvironment`          | A captura foi rejeitada porque o ambiente de execução não é considerado confiável.                                                                       |
| `SuspiciousActivity`            | A captura foi rejeitada porque o dispositivo apresentou padrões de atividade associados a um ataque.                                                     |
| `UntrustedDevice`               | A captura foi rejeitada porque não foi possível confiar que o dispositivo fosse o que afirma ser.                                                        |
| `SdkIntegrityViolation`         | A captura foi rejeitada porque o SDK de captura ou suas bibliotecas parecem ter sido alterados.                                                          |
| `UntrustedCorruptedPayload`     | A captura foi rejeitada porque o payload parece estar corrompido ou manipulado.                                                                          |
| `UntrustedContent`              | A captura foi rejeitada porque foi detectado um ataque de injeção.                                                                                       |
| `UntrustedContentLowConfidence` | A captura foi rejeitada porque o serviço detectou indícios de um ataque de injeção com menor confiança; ainda assim, deve ser tratada como uma rejeição. |