> ## 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 STA — o alvo de ambiente do BACEN, armazenamento de objetos compatível com S3, chaves-mestras de criptografia de envelope e o trust store.
O Lerian STA é o rail de propriedade da Lerian que transmite e recebe arquivos com o hub STA do BACEN. 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 STA.
Nas tabelas abaixo, a coluna **Padrão / Obrigatória** mostra o valor padrão; um qualificador em negrito (ex: **Obrigatória**, **Obrigatória em produção**) 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` | `:4028` | Endereço de escuta HTTP principal. As probes de liveness, readiness, metrics e version se vinculam a essa mesma porta. |
| `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. Deve ser um UUID válido. |
| `BACEN_ENVIRONMENT` | `homologation` | Seleciona o alvo STA do BACEN upstream para a probe de conectividade: `homologation` (staging) ou `production` (produção). Um valor não reconhecido usa `homologation` como fallback, de modo que um stack fora de produção não possa rotear tráfego para o serviço real do BACEN. |
O Lerian STA 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.
## Armazenamento de objetos
O Lerian STA persiste os bytes de transferência e os downloads de entrada em um object store compatível com S3. Cada subsistema configura sua própria conexão através do AWS SDK, então a mesma fiação atende AWS S3, MinIO ou um store local.
| Variável | Padrão / Obrigatória | Descrição |
| -------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `TRANSFER_OBJECT_STORAGE_BUCKET` | **Obrigatória em produção** | Bucket que armazena ambas as direções de transferência, keyed por prefixo de direção. O boot é recusado se estiver vazio em produção. |
| `TRANSFER_INBOUND_ENABLED` | `false` | Habilita o pipeline de transferência de entrada (puxada pelo BACEN). Quando `true`, `TRANSFER_OBJECT_STORAGE_BUCKET` é obrigatório em produção. |
| `TRANSFER_INBOUND_MAX_FILE_SIZE_BYTES` | `5368709120` | Teto do tamanho de arquivo de entrada anunciado pelo BACEN (padrão 5 GiB). Arquivos maiores são skip-listed antes de qualquer byte ser escrito. |
| `AWS_REGION` | `us-east-1` | Região para as conexões de object store e M2M. |
| `AWS_ACCESS_KEY_ID` | — | Access key para o object store. Sensível. Deixe não definido quando uma IAM role anexada fornece as credenciais. |
| `AWS_SECRET_ACCESS_KEY` | — | Secret key para o object store. Sensível. Deixe não definido quando uma IAM role anexada fornece as credenciais. |
## Criptografia de envelope
As credenciais de operador são protegidas com criptografia de envelope AES-GCM. O material de chave-mestra é sempre obrigatório — o processo do manager aborta o boot se ele estiver ausente ou malformado.
| Variável | Padrão / Obrigatória | Descrição |
| ------------------------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MASTER_KEY_PROVIDER` | `envvar` | Origem da chave de criptografia de envelope: `envvar` (chave lida de `MASTER_KEYS`) ou `aws-kms` (chave envelopada por um cloud KMS). |
| `MASTER_KEY_VERSION` | `v1` · **Obrigatória** | Seleciona a versão de chave-mestra atualmente ativa. |
| `MASTER_KEYS` | **Obrigatória** | Pares `version:key` separados por vírgula. Sensível. Sob `envvar` cada chave é uma chave AES-256 de 32 bytes; sob `aws-kms` cada valor é um blob envelopado. Obtenha do seu gerenciador de segredos — um valor ausente ou malformado aborta o boot. |
| `MASTER_KEY_KMS_KEY_ID` | **Obrigatória se `aws-kms`** | Referência à chave cloud-KMS que envelopa as chaves-mestras. O material de chave nunca entra no processo; apenas a referência é passada. |
| `CREDENTIALS_RECOVERY_ON_BOOT` | `true` | Executa a varredura de recuperação de credenciais do lado do worker uma vez no boot para resolver credenciais deixadas em meio a uma rotação por um processo anterior. |
## Trust store
Cada tenant faz upload dos certificados-raiz X.509 em que o Lerian STA confia ao estabelecer TLS mútuo com o BACEN. O módulo de trust store fica sempre ligado. Os corpos PEM dos certificados são persistidos no object store, então a conexão com o bucket do trust store é obrigatória.
| Variável | Padrão / Obrigatória | Descrição |
| --------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `TRUST_STORE_S3_BUCKET` | **Obrigatória** | Bucket que armazena os PEMs de certificado do trust store por tenant. O boot falha sem ele. |
| `TRUST_STORE_S3_REGION` | `us-east-1` | Região para o bucket do trust store. |
| `TRUST_STORE_S3_ENDPOINT` | — | Endpoint do object store. Deixe vazio para usar o endpoint padrão do AWS S3 como fallback. |
| `TRUST_STORE_S3_PATH_STYLE` | `false` | Usa endereçamento path-style. Obrigatório para MinIO ou um store local; deixe `false` para AWS S3. |
| `TRUST_STORE_MAX_CERT_SIZE_BYTES` | `65536` | Tamanho máximo aceito de um PEM de certificado enviado. |
| `TRUST_STORE_EXPIRING_SOON_DAYS` | `30` | Janela, em dias, a partir da qual um certificado é reportado como próximo do vencimento. Ajustável pelo operador com hot reload. |
| `TRUST_STORE_DEFAULT_PAGE_SIZE` | `25` | Tamanho de página padrão para a API de listagem do trust store. |
| `TRUST_STORE_MAX_PAGE_SIZE` | `100` | Tamanho de página máximo para a API de listagem do trust store. |
O Lerian STA roda seu pipeline de auditoria em um worker dedicado: um publisher de outbox, um consumidor de auditoria hash-chained, um gerenciador de partições, uma limpeza de outbox e um gerador assíncrono de exportação de auditoria. Eles rodam quando a multi-tenancy e o broker estão habilitados e são ajustados através das famílias `AUDIT_PUBLISHER_*`, `AUDIT_CONSUMER_*`, `AUDIT_PARTITION_*`, `AUDIT_CLEANUP_*`, `AUDIT_EXPORT_GENERATOR_*` e `AUDIT_EXPORT_RATE_LIMIT_*`, cada uma entregando padrões funcionais.