> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Variáveis de ambiente
> Variáveis de ambiente em tempo de deploy para o Lerian SISBAJUD: backend de KMS, armazenamento de objetos S3, chaves de criptografia por envelope, workers e ledger Midaz.
O Lerian SISBAJUD é o trilho de propriedade da Lerian que cumpre ordens judiciais de bloqueio de ativos e protege os dados pessoais que elas carregam. Você define essas variáveis no momento do deploy. Elas apenas entram em vigor depois de um reinício do serviço. [Fundamentos de configuração do BYOC](/pt/reference/byoc-configuration) documenta a base universal que todo serviço Go da Lerian compartilha: servidor, armazenamento de dados, multi-tenancy, telemetria, autenticação de plugin e licenciamento. Esta página cobre apenas as variáveis específicas do Lerian SISBAJUD.
Nas tabelas abaixo, a coluna **Padrão / Obrigatório** mostra o valor padrão. Um qualificador em negrito (por exemplo, **Obrigatório** ou **Obrigatório se habilitada**) marca as variáveis que você deve definir. `—` significa que não há padrão. Qualquer variável sinalizada como **Sensível** carrega material de credencial ou chave. Injete-a a partir do seu gerenciador de segredos no momento do deploy. Nunca faça commit de um valor.
## Serviço e runtime
| Variável | Padrão / Obrigatório | Descrição |
| --------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SERVER_ADDRESS` | — | Endereço principal de escuta HTTP; sem padrão no código, então defina-o explicitamente (o deploy de referência usa `:4029`). As sondas de liveness, readiness, métricas e versão usam essa mesma porta. |
| `ENVIRONMENT_NAME` | — | Ambiente de runtime: `local`, `development`, `staging`, `e2e`, `test` ou `production`. `ENV_NAME` é aceito como nome alternativo. Quando não definida, permanece vazia e é tratada como semelhante a produção, então os controles de segurança mais rígidos armam com falha fechada. |
| `SYSTEMPLANE_ENABLED` | `false` | Habilita a API administrativa de configuração em runtime do [Systemplane](/pt/reference/platform/systemplane/overview) sob o prefixo `/system` na porta principal. Desabilitada por padrão (modo apenas variáveis de ambiente). |
| `DEFAULT_TENANT_ID` | **Obrigatório no modo single-tenant** | UUID do tenant usado no modo single-tenant. Não há padrão de string efetivo: defina explicitamente um UUID válido para uma operação single-tenant utilizável. O tenant é o limite de isolamento do banco de dados e pode conter várias instituições; cada instituição roteia pelo seu próprio identificador dentro do tenant. Com a autenticação desabilitada, o trilho também usa esse UUID como sua única instituição configurada. |
O Lerian SISBAJUD expõe `/health` (liveness), `/readyz` (readiness), `/version` e `/metrics` na porta principal. Quando você habilita a multi-tenancy, ele também expõe `GET /readyz/tenant/{id}`. Consulte [Health e readiness](/pt/reference/health-and-readiness) para o contrato das sondas.
## Backend de segurança
O serviço valida o provedor de KMS na inicialização. Ele seleciona o backend que protege os dados de apreensão determinada judicialmente com criptografia por envelope. Em produção, um valor não definido ou não suportado falha a inicialização de forma fechada. Fora de produção, o padrão é `vault`.
| Variável | Padrão / Obrigatório | Descrição |
| -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `KMS_PROVIDER` | `vault` (fora de produção) · **Obrigatório em produção** | Gerenciador de chaves de criptografia por envelope: `vault` (HashiCorp Vault Transit) ou `aws` (AWS KMS). Lido uma vez na inicialização; não é recarregável a quente. Não há provedor em memória. |
`KMS_PROVIDER=vault` exige as variáveis do Vault abaixo. `KMS_PROVIDER=aws` exige a `AWS_REGION` compartilhada. As credenciais do conector por instituição ficam seladas dentro dos metadados de configuração da instituição, sob uma KEK de classe credenciais. Nenhum seletor de ambiente escolhe o armazenamento delas. `KMS_PROVIDER` usa `vault` como padrão quando não definida fora de produção. Em produção, você deve defini-la explicitamente ou a inicialização falha de forma fechada.
### Vault (quando `KMS_PROVIDER=vault`)
| Variável | Padrão / Obrigatório | Descrição |
| -------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `VAULT_ADDR` | **Obrigatório para o provedor Vault** | Endereço do Vault do cliente. |
| `VAULT_AUTH_METHOD` | `token` | Método de autenticação: `token` (`VAULT_TOKEN` estático) ou `approle` (role id e secret id do AppRole). |
| `VAULT_TOKEN` | **Obrigatório se `token`, em produção** | Token de serviço para o Vault. Sensível. Fora de produção, usa um token de desenvolvimento como fallback. |
| `VAULT_APPROLE_ROLE_ID` | **Obrigatório se `approle`** | Role id do AppRole. Sensível. |
| `VAULT_APPROLE_SECRET_ID` | **Obrigatório se `approle`** | Secret id do AppRole. Sensível. |
| `VAULT_TRANSIT_MOUNT_PATH` | `transit` | Caminho de mount do engine Transit usado para a criptografia por envelope. |
\| `VAULT_TOKEN_RENEW_ENABLED` | `true` | Executa um renovador em segundo plano que atualiza o token do Vault antes que o lease dele expire. |
\| `VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC` | `60` | Piso, em segundos, entre tentativas de renovação. |
\| `VAULT_TIMEOUT_SEC` | `15` | Timeout por requisição, em segundos, para cada round-trip ao Vault. |
### AWS (quando `KMS_PROVIDER=aws`)
| Variável | Padrão / Obrigatório | Descrição |
| ------------------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AWS_REGION` | **Obrigatório com `KMS_PROVIDER=aws`** | Região para o adaptador do AWS KMS. A inicialização falha de forma fechada quando `KMS_PROVIDER=aws` e ela está em branco. As credenciais são resolvidas pela cadeia padrão do AWS SDK. |
| `AWS_ENDPOINT_URL` | — | Substituição de endpoint compatível com AWS. Deixe não definida em ambientes AWS reais para que o SDK use seus endpoints padrão. |
## Ciclo de vida de criptografia
A criptografia por envelope usa uma chave de dados por registro, selada sob a chave mestra da instituição, além de um índice cego para busca por correspondência exata em identificadores fiscais.
| Variável | Padrão / Obrigatório | Descrição |
| ---------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SISBAJUD_DEK_CACHE_TTL` | `5m` | Tempo de vida de uma chave de criptografia de dados desembrulhada no cache em memória antes que o KMS seja solicitado a desembrulhá-la novamente. String de duração no formato Go. |
| `SISBAJUD_DEK_CACHE_MAX_ENTRIES` | `50000` | Teto de primitivas de chave de dados em cache; limita o heap durante uma descriptografia de lote grande. |
| `SISBAJUD_HMAC_COEXISTENCE_WINDOW` | `720h` | Janela durante a qual os hashes do índice cego da versão anterior da chave HMAC continuam consultáveis durante uma rotação de chave. String de duração no formato Go. |
| `KEK_REWRAP_BACKFILL_ENABLED` | `false` | Habilita a varredura em segundo plano que avança as linhas de chave de dados atrasadas para a versão ativa da chave mestra depois de uma rotação. |
| `REHASH_BACKFILL_ENABLED` | `false` | Habilita a varredura em segundo plano que recalcula o hash das linhas atrasadas do índice cego para a nova versão primária da chave HMAC. |
## Workers de domínio
O processamento de ordens judiciais roda como um conjunto de crons em segundo plano por instituição. Todos vêm desabilitados por padrão, exceto o reaper de processing lock, que roda por padrão. Os workers usam os controles de cadência `*_SCAN_INTERVAL` (segundos) e `*_BATCH_SIZE` (quando aplicável).
| Variável | Padrão / Obrigatório | Descrição |
| -------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EXECUTION_ENABLED` | `false` | Chave mestra para o motor de execução de ordens. Quando desabilitada, o orquestrador FIFO e o dispatch downstream permanecem inativos. |
| `ORCHESTRATOR_LOCK_TTL` | `30` | Lease do lock de execução por sujeito, em segundos. |
| `ORCHESTRATOR_RENEW_INTERVAL` | `10` | Cadência, em segundos, na qual o worker proprietário renova o lock. Deve ficar estritamente abaixo de `ORCHESTRATOR_LOCK_TTL`, ou a inicialização falha de forma fechada. |
| `PROCESSING_LOCK_REAPER_ENABLED` | `true` | Habilita o reaper em segundo plano que exclui linhas de processing lock expiradas para cada tenant. |
| `PROCESSING_LOCK_REAPER_INTERVAL_SEC` | `300` | Cadência de varredura do reaper em segundos. Quando essa variável não está definida ou não é positiva, o serviço usa 300 segundos. |
| `UNBLOCK_EXECUTION_SCAN_INTERVAL` | `60` | Cadência de varredura de desbloqueios pendentes em segundos. Compartilha o controle de `EXECUTION_ENABLED`. |
| `UNBLOCK_EXECUTION_BATCH_SIZE` | `500` | Ordens de desbloqueio pendentes processadas por passagem de tenant. |
| `PERMANENT_BLOCK_EXPIRY_ENABLED` | `false` | Habilita a varredura diária que expira bloqueios permanentes que passaram do prazo. |
| `RECONCILIATION_ENABLED` | `false` | Habilita a varredura que concilia ordens em monitoramento com o ledger e persiste as divergências detectadas. |
| `RETURN_FILE_GENERATION_ENABLED` | `false` | Habilita a geração de arquivos de retorno do SISBAJUD para ordens terminais ainda não retornadas. |
| `INFORMATION_RETURN_FILE_GENERATION_ENABLED` | `false` | Habilita a geração de arquivos de resposta de informação AJUD309. |
| `SLA_ALERT_ENABLED` | `false` | Habilita o avaliador que classifica ordens ativas por faixa de risco de SLA e emite as faixas como métricas. |
| `RETURN_FILE_ENVIRONMENT` | `HOMOLOGATION` | Ambiente regulatório registrado nos arquivos de retorno gerados. |
## Armazenamento de objetos
O Lerian SISBAJUD grava artefatos de apreensão determinada judicialmente em um armazenamento de objetos compatível com S3, já criptografados. A camada de blob nunca vê o texto plano.
| Variável | Padrão / Obrigatório | Descrição |
| ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SEAWEEDFS_S3_ENDPOINT` | `http://localhost:8333` | Endpoint do armazenamento de objetos compatível com S3. Falhas na conexão do armazenamento não são fatais: o serviço inicializa e a sonda de readiness informa o armazenamento como indisponível. |
| `SEAWEEDFS_BUCKET` | `sisbajud` | Bucket para artefatos de remessa e retorno (já criptografados). |
| `SEAWEEDFS_REGION` | `us-east-1` | Rótulo de região S3 exigido pelo AWS SDK. |
| `SEAWEEDFS_ACCESS_KEY` | — | Chave de acesso do armazenamento de objetos. Sensível. Deixe em branco quando o armazenamento não exigir autenticação. |
| `SEAWEEDFS_SECRET_KEY` | — | Chave secreta do armazenamento de objetos. Sensível. Deixe em branco quando o armazenamento não exigir autenticação. |
| `STA_INBOUND_BUCKET` | `sta-files` | Bucket que contém os objetos de remessa brutos para os quais uma notificação de recepção aponta. |
| `STA_FILE_LOCK_TTL` | `5` | TTL do lock de processamento por arquivo, em minutos. |
## Conector do ledger Midaz
O Lerian SISBAJUD lê saldos e bloqueios por meio do ledger Midaz. `MIDAZ_BASE_URL` é um fallback opcional para todo o serviço. Os metadados de conector por instituição têm precedência.
| Variável | Padrão / Obrigatório | Descrição |
| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MIDAZ_BASE_URL` | — (fallback opcional) | URL base do ledger Midaz. Usada apenas quando os metadados por instituição não fornecem uma URL. A resolução do conector falha de forma fechada apenas se nenhum dos dois fornecer uma URL. |
| `MIDAZ_AUTH_ENABLED` | `false` | Habilita a autenticação máquina a máquina com o Midaz. |
| `MIDAZ_AUTH_ADDRESS` | **Obrigatório se habilitada** | Endereço do serviço de autenticação para emitir tokens do Midaz. |
| `MIDAZ_CLIENT_ID` | **Obrigatório se habilitada** | Client id OAuth para o Midaz. Ignorado no modo multi-tenant (resolvido por tenant). |
| `MIDAZ_CLIENT_SECRET` | **Obrigatório se habilitada** | Client secret OAuth para o Midaz. Sensível. Ignorado no modo multi-tenant (resolvido por tenant). |