Configuração

O Agent é configurado inteiramente por variáveis de ambiente. Nenhuma credencial tem valor padrão — um Agent que sobe com chave de exemplo é um Agent que assina com chave de exemplo — então as variáveis marcadas como obrigatórias precisam estar presentes, ou o boot falha com erro de configuração (código de saída 2).

Esta página é a referência completa. Se você só quer colocar o processo no ar, comece por Instalação; se ainda não tem as credenciais, elas vêm do provisionamento.

Variáveis de ambiente

Plataforma e credenciais

Variável	Obrigatória	Default	Propósito
LOOTFY_BASE_URL	sim	—	Base da API, com o prefixo de versão (ex.: https://api.lootfy.gg/v1). Uma barra final é removida automaticamente.
LOOTFY_SERVICE_API_KEY	sim	—	Sua API key de serviço, enviada no header x-service-api-key. Não participa das rotas transportadas pelo client (signature-only).
LOOTFY_JWS_KID	sim	—	O kid da sua chave de assinatura, como a plataforma a conhece. Vai no header do JWS.
LOOTFY_JWS_PRIVATE_KEY_FILE	ver nota	— (o .env.example sugere /etc/lootfy/server-key.pem)	Caminho para o arquivo PEM da sua chave privada de assinatura. Caminho preferido.
LOOTFY_JWS_PRIVATE_KEY	ver nota	—	Alternativa inline: o PEM na própria variável. Desencorajado (ver abaixo).

Prefira o arquivo à variável inline

Você precisa de uma das duas: LOOTFY_JWS_PRIVATE_KEY_FILE (caminho) ou LOOTFY_JWS_PRIVATE_KEY (PEM inline). Prefira o arquivo. Um PEM em variável de ambiente vaza em ps, em dump de container e em painel de orquestrador — lugares onde um segredo escapa sem ninguém perceber. Se o arquivo estiver configurado, é ele que vale; a variável inline só é lida quando não há caminho de arquivo. O .env.example do Agent já vem com o caminho apontando para /etc/lootfy/server-key.pem, mas esse valor é uma sugestão do exemplo, não um default embutido no código: se você não definir nenhuma das duas, o boot falha pedindo a chave.

Porta de controle (assina)

Variável	Obrigatória	Default	Propósito
LOOTFY_CONTROL_HOST	não	127.0.0.1	Endereço em que a porta de controle escuta. Deve ser loopback — ver o aviso abaixo.
LOOTFY_CONTROL_PORT	não	8899	Porta em que a porta de controle escuta.

A porta de controle recusa endereço público

A porta de controle assina sob demanda: quem a alcança detém a autoridade do seu servidor na Lootfy, e nenhuma checagem posterior recupera isso. Por isso o Agent recusa subir se LOOTFY_CONTROL_HOST for um bind que expõe a porta para fora da máquina — os valores rejeitados no boot são 0.0.0.0, ::, * e o valor vazio. Mantenha em 127.0.0.1 e ponha o servidor de jogo na mesma host, ou faça um túnel. Publicar essa porta é entregar a caneta a quem alcançar a máquina.

Interface de spool (interface C)

Variável	Obrigatória	Default	Propósito
LOOTFY_SPOOL_DIR	não	— (desligado)	Diretório de spool da interface C. Quando ausente, o modo spool fica desligado. Também é pré-requisito da porta de webhook.

Porta de webhook (verifica)

Variável	Obrigatória	Default	Propósito
LOOTFY_PLATFORM_PUBLIC_KEY_FILE	ver “regra dos três”	—	Caminho para o PEM da chave pública da plataforma, usada para verificar os webhooks.
LOOTFY_PLATFORM_PUBLIC_KEY	ver “regra dos três”	—	Alternativa inline à chave pública da plataforma.
LOOTFY_PLATFORM_KID	ver “regra dos três”	—	O kid que a plataforma põe no header dos webhooks.
LOOTFY_WEBHOOK_HOST	não	127.0.0.1	Endereço em que a porta de webhook escuta.
LOOTFY_WEBHOOK_PORT	não	8898	Porta em que a porta de webhook escuta.
LOOTFY_WEBHOOK_PATH	não	/lootfy/webhook	Path exato onde a plataforma faz o POST. Precisa casar com o webhookUrl registrado no provisionamento.
LOOTFY_JWS_MAX_AGE	não	300	Janela de frescor, em segundos, do envelope recebido no webhook.
LOOTFY_JWS_CLOCK_SKEW	não	60	Tolerância de desvio de relógio, em segundos, na verificação do webhook.

Envelope e log

Variável	Obrigatória	Default	Propósito
LOOTFY_ENVELOPE_TTL	não	120	Validade, em segundos, do envelope que o Agent assina. Curto de propósito. Precisa ser um número ≥ 5, ou o boot falha.
LOOTFY_LOG_LEVEL	não	info	Nível de log: debug, info ou error.

Atalho de bancada

Existe uma variável LOOTFY_BENCH_FILE que aponta para o arquivo que a ferramenta de setup da bancada grava, cobrindo BASE_URL, API key, kid, chave privada e chave da plataforma de uma vez. É um atalho de desenvolvimento contra a bancada — em produção, configure cada variável explicitamente.

A regra dos três para ligar o webhook

A porta de webhook não sobe sozinha. Ela só é ativada quando os três pré-requisitos estão presentes ao mesmo tempo: a chave pública da plataforma (LOOTFY_PLATFORM_PUBLIC_KEY_FILE ou LOOTFY_PLATFORM_PUBLIC_KEY), o kid da plataforma (LOOTFY_PLATFORM_KID) e um diretório de spool (LOOTFY_SPOOL_DIR). O diretório de spool entra porque é por ele que o evento verificado chega ao seu servidor — o canal de eventos vive no spool.

Faltando qualquer um dos três, a porta de webhook fica desligada e o Agent segue funcionando normalmente para as chamadas de saída. Isso é intencional: uma instalação que só faz chamadas de saída (assinar e enviar) não precisa receber webhook, e não faria sentido recusar o boot por causa disso. O Agent registra no log que a porta de webhook está desligada e diz qual dos três está faltando.

Verificar exige a chave; sem ela, não sobe a porta

A porta de webhook existe para verificar a assinatura da plataforma. Sem a chave pública da Lootfy, ela não teria como verificar nada — então o Agent prefere não subir a porta a subir uma porta que aceita qualquer coisa. É a mesma disciplina da porta de controle, do outro lado do espelho.

Exemplo de arquivo de configuração

Um arquivo de ambiente típico, com placeholders no lugar dos segredos, para uma instalação que faz chamadas de saída e recebe webhooks:

# Plataforma e credenciais
LOOTFY_BASE_URL=https://api.lootfy.gg/v1
LOOTFY_SERVICE_API_KEY=<sua-api-key>
LOOTFY_JWS_KID=<seu-kid>
LOOTFY_JWS_PRIVATE_KEY_FILE=/etc/lootfy/server-key.pem

# Porta de controle (assina — mantenha em loopback)
LOOTFY_CONTROL_HOST=127.0.0.1
LOOTFY_CONTROL_PORT=8899

# Interface C (spool) — também necessária para o webhook
LOOTFY_SPOOL_DIR=/home/server/lootfy-spool

# Porta de webhook (verifica) — a regra dos três
LOOTFY_PLATFORM_PUBLIC_KEY_FILE=/etc/lootfy/platform-key.pub
LOOTFY_PLATFORM_KID=<kid-da-plataforma>
LOOTFY_WEBHOOK_HOST=127.0.0.1
LOOTFY_WEBHOOK_PORT=8898
LOOTFY_WEBHOOK_PATH=/lootfy/webhook

# Envelope e log
LOOTFY_ENVELOPE_TTL=120
LOOTFY_LOG_LEVEL=info

Segredos no log ficam redigidos

Não se preocupe em vazar credencial pelo log de operação: o Agent redige automaticamente os campos sensíveis (chave privada, API key, cabeçalhos de assinatura, senha, documento) em qualquer nível de log. O que ele nunca controla é o seu arquivo de configuração — esse, guarde com as permissões certas.

Próximo: interfaces locais Como o seu servidor conversa com o Agent — HTTP em loopback e spool de diretório.