> ## 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 distintivas do Lerian SISBAJUD — os backends de KMS e de secret store, armazenamento de objetos compatível com S3, o ciclo de vida cripto, os workers de domínio e o conector do ledger Midaz.

O Lerian SISBAJUD é o rail de propriedade da Lerian que cumpre ordens judiciais de bloqueio de ativos e protege os dados pessoais que elas carregam. Essas variáveis são definidas no momento do deploy e exigem uma reinicialização do serviço para entrar em vigor. O backbone universal que todo serviço Go da Lerian compartilha — servidor, datastores, multi-tenancy, telemetria, autenticação de plugin e licenciamento — é documentado uma única vez na [referência de configuração BYOC](/pt/reference/byoc-configuration); esta página cobre apenas as variáveis distintivas do Lerian SISBAJUD.

Nas tabelas abaixo, a coluna **Padrão / Obrigatória** mostra o valor padrão; um qualificador em negrito (ex: **Obrigatória**, **Obrigatória se habilitado**) marca variáveis que devem ser definidas. `—` significa que não há padrão. Qualquer variável marcada como **Sensível** carrega material de credencial ou de chave — injete-a a partir do seu gerenciador de segredos no momento do deploy e nunca faça commit de um valor.

## Serviço e runtime

| Variável              | Padrão / Obrigatória                   | Descrição                                                                                                                                                                                                             |
| --------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SERVER_ADDRESS`      | `:4029`                                | Endereço de escuta HTTP principal. As probes de liveness, readiness, metrics e version se vinculam a essa mesma porta.                                                                                                |
| `ENVIRONMENT_NAME`    | `staging`                              | Ambiente de runtime: `staging` ou `production`. Arma controles de segurança mais estritos em `production`. `ENV_NAME` é aceito como nome alternativo.                                                                 |
| `SYSTEMPLANE_ENABLED` | `false`                                | Habilita a API de administração de configuração de runtime do [Systemplane](/pt/reference/systemplane/overview) sob o prefixo `/system` na porta principal. Desligada por padrão (modo apenas variáveis de ambiente). |
| `DEFAULT_TENANT_ID`   | `11111111-1111-1111-1111-111111111111` | UUID de tenant usado no modo single-tenant. Aqui o tenant equivale à instituição. Deve ser um UUID válido.                                                                                                            |

<Note>
  O Lerian SISBAJUD expõe `/health` (liveness) e `/readyz` (readiness) na porta principal, além de `/version` e `/metrics`, e — quando a multi-tenancy está habilitada — `GET /readyz/tenant/{id}`. Consulte [Saúde e prontidão](/pt/reference/health-and-readiness) para o contrato das probes.
</Note>

## Backends de segurança

Ambos os seletores são validados no boot; um valor não definido ou não suportado falha o boot fechado. Eles escolhem os backends que protegem os dados de bloqueio determinados por ordem judicial.

| Variável                           | Padrão / Obrigatória      | Descrição                                                                                                                                                                                                                                                               |
| ---------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `KMS_PROVIDER`                     | `vault` · **Obrigatória** | Gerenciador de chaves de criptografia de envelope: `vault` (HashiCorp Vault Transit) ou `aws` (cloud KMS). Lido uma vez no boot; não recarregável a quente. Não há provider em memória.                                                                                 |
| `SECRET_STORE_PROVIDER`            | `local` · **Obrigatória** | De onde os segredos do serviço são lidos: `vault` ou `local`. `aws-secrets-manager` é um valor reconhecido, mas um adaptador diferido (Fase 4) que ainda não está conectado — selecioná-lo falha o boot; use `vault` ou `local` hoje.                                   |
| `CONNECTOR_CREDS_USE_SECRET_STORE` | `false`                   | Resolve credenciais de conector por instituição a partir do secret store em vez das credenciais de ambiente. Apenas `vault` ou `local` estão conectados para credenciais de conector hoje; habilitar isto com `SECRET_STORE_PROVIDER=aws-secrets-manager` falha o boot. |

<Note>
  Cada seletor puxa seu próprio bloco de acompanhamento, todos validados no boot: `vault` (para qualquer um dos seletores) requer as variáveis do Vault abaixo; `KMS_PROVIDER=aws` usa a `AWS_REGION` compartilhada (padrão `us-east-1`); `SECRET_STORE_PROVIDER=local` lê os segredos do ambiente e não precisa de nenhum backend externo. O adaptador `aws-secrets-manager` está diferido e ainda não está conectado — selecioná-lo (para segredos normais do serviço ou para credenciais de conector) falha o boot; use `vault` ou `local`. `SECRET_STORE_PROVIDER` é `local` por padrão quando não definido, em ambientes não produtivos.
</Note>

### Vault (quando `KMS_PROVIDER=vault` ou `SECRET_STORE_PROVIDER=vault`)

| Variável                             | Padrão / Obrigatória                  | Descrição                                                                                               |
| ------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `VAULT_ADDR`                         | **Obrigatória para o provider 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ória se `token`**            | Token de serviço para o Vault. Sensível.                                                                |
| `VAULT_APPROLE_ROLE_ID`              | **Obrigatória se `approle`**          | Role id do AppRole. Sensível.                                                                           |
| `VAULT_APPROLE_SECRET_ID`            | **Obrigatória se `approle`**          | Secret id do AppRole. Sensível.                                                                         |
| `VAULT_TRANSIT_MOUNT_PATH`           | `transit`                             | Mount path do engine Transit usado para criptografia de envelope.                                       |
| `VAULT_KV_MOUNT`                     | `sisbajud-secrets`                    | Mount path do engine KV que armazena as credenciais de conector por instituição.                        |
| `VAULT_TOKEN_RENEW_ENABLED`          | `true`                                | Executa um renewer em segundo plano que renova o token do Vault antes de o lease expirar.               |
| `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 do Vault.                                     |

### AWS (quando `KMS_PROVIDER=aws` ou `SECRET_STORE_PROVIDER=aws-secrets-manager`)

| Variável           | Padrão / Obrigatória | Descrição                                                                                                                                                                                                                                                                                   |
| ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AWS_REGION`       | `us-east-1`          | Região compartilhada para os adaptadores de AWS — AWS KMS hoje, e o secret-store de AWS quando estiver conectado. Padrão `us-east-1` quando não definido; defina explicitamente para corresponder à região da sua conta. As credenciais são resolvidas através da cadeia padrão do AWS SDK. |
| `AWS_ENDPOINT_URL` | —                    | Override de endpoint compatível com AWS. Deixe não definido em ambientes AWS reais para que o SDK use seus endpoints padrão.                                                                                                                                                                |

## Ciclo de vida cripto

A criptografia de envelope usa uma data key por registro selada sob a chave-mestra da instituição, além de um blind index para busca por correspondência exata em identificadores fiscais.

| Variável                           | Padrão / Obrigatória | Descrição                                                                                                                                                    |
| ---------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SISBAJUD_DEK_CACHE_TTL`           | `5m`                 | Tempo de vida de uma data-encryption key desenvelopada no cache em memória antes de o KMS ser solicitado a desenvelopar novamente. String de duração Go.     |
| `SISBAJUD_DEK_CACHE_MAX_ENTRIES`   | `50000`              | Teto de primitivas de data key em cache; limita o heap durante um decrypt em batch grande.                                                                   |
| `SISBAJUD_HMAC_COEXISTENCE_WINDOW` | `720h`               | Janela durante a qual hashes de blind index da versão anterior de chave HMAC permanecem consultáveis ao longo de uma rotação de chave. String de duração Go. |
| `KEK_REWRAP_BACKFILL_ENABLED`      | `false`              | Habilita a varredura em segundo plano que avança linhas de data key atrasadas para a versão de chave-mestra ativa após uma rotação.                          |
| `REHASH_BACKFILL_ENABLED`          | `false`              | Habilita a varredura em segundo plano que re-hasheia linhas de blind index atrasadas para a nova versão primária de chave HMAC.                              |

## Workers de domínio

O processamento de ordens judiciais roda como um conjunto de crons em segundo plano por instituição. Cada um fica desligado por padrão e compartilha os parâmetros de cadência `*_SCAN_INTERVAL` (segundos) e `*_BATCH_SIZE`.

| Variável                                     | Padrão / Obrigatória | Descrição                                                                                                                                                   |
| -------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EXECUTION_ENABLED`                          | `false`              | Chave mestra para o engine de execução de ordens. Quando desligada, o orquestrador FIFO e o dispatch downstream permanecem dormentes.                       |
| `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 permanecer estritamente abaixo de `ORCHESTRATOR_LOCK_TTL` ou o boot falha fechado. |
| `UNBLOCK_EXECUTION_SCAN_INTERVAL`            | `60`                 | Cadência da varredura de desbloqueios pendentes em segundos. Compartilha o gate `EXECUTION_ENABLED`.                                                        |
| `UNBLOCK_EXECUTION_BATCH_SIZE`               | `500`                | Ordens de desbloqueio pendentes processadas por passada de tenant.                                                                                          |
| `PERMANENT_BLOCK_EXPIRY_ENABLED`             | `false`              | Habilita a varredura diária que expira bloqueios permanentes após seu prazo.                                                                                |
| `RECONCILIATION_ENABLED`                     | `false`              | Habilita a varredura que reconcilia ordens de monitoramento contra o ledger e persiste as lacunas detectadas.                                               |
| `RETURN_FILE_GENERATION_ENABLED`             | `false`              | Habilita a geração de arquivos de retorno SISBAJUD para ordens terminais 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 carimbado nos arquivos de retorno gerados.                                                                                             |

## Armazenamento de objetos

Os artefatos de bloqueio determinados por ordem judicial são escritos em um object store compatível com S3, já criptografados — a camada de blob nunca vê texto plano.

| Variável                | Padrão / Obrigatória | Descrição                                                                                          |
| ----------------------- | -------------------- | -------------------------------------------------------------------------------------------------- |
| `SEAWEEDFS_S3_ENDPOINT` | **Obrigatória**      | Endpoint do object store compatível com S3.                                                        |
| `SEAWEEDFS_BUCKET`      | `sisbajud`           | Bucket para artefatos de remessa e de retorno (já criptografados).                                 |
| `SEAWEEDFS_REGION`      | `us-east-1`          | Rótulo de região S3 exigido pelo AWS SDK.                                                          |
| `SEAWEEDFS_ACCESS_KEY`  | —                    | Access key do object store. Sensível. Deixe em branco quando o store não exigir auth.              |
| `SEAWEEDFS_SECRET_KEY`  | —                    | Secret key do object store. Sensível. Deixe em branco quando o store não exigir auth.              |
| `STA_INBOUND_BUCKET`    | `sta-files`          | Bucket que armazena 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 através do ledger Midaz. `MIDAZ_BASE_URL` é obrigatória em todo o serviço.

| Variável              | Padrão / Obrigatória          | Descrição                                                                                         |
| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------- |
| `MIDAZ_BASE_URL`      | **Obrigatória**               | URL base do ledger Midaz. O boot falha fechado sem ela.                                           |
| `MIDAZ_AUTH_ENABLED`  | `false`                       | Habilita a autenticação machine-to-machine para o Midaz.                                          |
| `MIDAZ_AUTH_ADDRESS`  | **Obrigatória se habilitado** | Endereço do serviço de auth para emitir tokens Midaz.                                             |
| `MIDAZ_CLIENT_ID`     | **Obrigatória se habilitado** | OAuth client id para o Midaz. Ignorado no modo multi-tenant (resolvido por tenant).               |
| `MIDAZ_CLIENT_SECRET` | **Obrigatória se habilitado** | OAuth client secret para o Midaz. Sensível. Ignorado no modo multi-tenant (resolvido por tenant). |