Skip to content
Varanda-orgPublic

Repository files navigation

varanda

Monorepo npm da fase 0 de uma rede social ponto a ponto no Holepunch (Hypercore, Hyperswarm e HyperDHT): o programa de terminal (varanda, varanda-serve), o aplicativo iOS, Android e web (apps/app), o site estático (apps/site) e as bibliotecas compartilhadas (packages/*). A referência normativa dos formatos é docs/protocol.md. O guia de desenvolvimento está em docs/development.md.

Estrutura do repositório

É um monorepo npm (workspaces packages/* e apps/*, um só package-lock.json na raiz).

  • apps/cli: o programa de linha de comando (varanda, varanda-serve), o semeador e a demo. README.
  • apps/app: aplicativo iOS, Android e web, com o worklet Bare que roda o nó no celular e a interface de membro. README.
  • apps/site: o site estático do Varanda (página de apresentação, logotipo e as fontes dos ícones do app). README, docs/site.md.
  • packages/core: o núcleo do protocolo e a sessão do nó, usados pelo CLI e pelo app (Node e Bare). README.
  • packages/rpc: o contrato JSON entre a interface e o nó. README.
  • deploy/seeder: imagem Docker, Compose e unidade systemd do semeador. Ver Operar o semeador.
  • docs/: protocol.md (referência normativa dos formatos), rpc.md (contrato da interface), design.md (documento de design), development.md, app.md, ios-gate.md, verification.md (verificação ponta a ponta do monorepo) e site.md (site estático). O índice está em docs/README.md.

O que é

Cada pessoa tem um diário assinado no próprio dispositivo. Seguidores e semeadores guardam cópias. O semeador só guarda um diário cujo bloco 0 traz um certificado de membro válido da associação em que ele confia. A identidade é a chave pública desse diário: 64 dígitos hexadecimais (32 bytes).

Quem acompanha outra pessoa pede o diário dela aos pares e ao semeador. Com o processo de sincronização da autora já encerrado, o semeador continua servindo a cópia que admitiu.

O semeador também tem certificado da mesma associação. Só um semeador verificado por esse certificado conta como admissão (admitted).

Requisitos

  • Node.js 20 ou mais novo (engines.node é >=20)
  • npm

O programa de terminal roda no Node e não tem etapa de compilação. O núcleo (packages/core) também roda no runtime Bare, dentro do aplicativo (apps/app; veja docs/development.md para compilar o app). Esta fase não usa o runtime Pear.

Contribuir

Guia completo em CONTRIBUTING.md.

  • Faça fork do repositório e abra um pull request contra main.
  • Comente na issue antes de começar, para alinhar escopo e evitar trabalho duplicado.
  • Use branch no formato <tipo>/<slug> (por exemplo fix/nome-curto).
  • No PR, referencie a issue com Closes #n.
  • Vulnerabilidades: siga SECURITY.md; não abra issue pública com detalhes sensíveis.

Licença

O código deste repositório é distribuído sob a PolyForm Noncommercial 1.0.0 (SPDX PolyForm-Noncommercial-1.0.0); o licenciante é Rodrigo Serviuc Pavezi. Usar, copiar e modificar o código é permitido para fins não comerciais, nos termos da licença. Usos comerciais não abrangidos pela licença dependem de autorização prévia do licenciante. É código-fonte disponível, não código aberto segundo a definição da Open Source Initiative (OSI). Ao abrir um PR, quem contribui concede ao licenciante uma licença para distribuir a contribuição sob quaisquer termos, sem CLA. Os detalhes, e os trechos de terceiros que continuam sob a MIT, estão na seção Licença de CONTRIBUTING.md.

Instalação

Na raiz deste repositório:

npm install

Os executáveis em bin/ na raiz são atalhos para apps/cli/bin/ (por exemplo bin/varanda.js).

O programa é node bin/varanda.js. A ajuda:

node bin/varanda.js help

--help e -h imprimem o mesmo texto. Os valores vão em separado: --flag valor. A forma --flag=valor é uma opção desconhecida (código 2).

Conceitos

Ajuda

node bin/varanda.js help imprime exatamente:

varanda — protótipo de rede social P2P (fase 0)
Uso: node bin/varanda.js <comando> [subcomando] [opções]
Comandos:
  assoc init|show|certify    chave da associação de teste e certificados de membro
  assoc certify-seeder       certifica a chave de um semeador (--seeder)
  assoc certify-issuer       certifica a chave do emissor do serviço de conta (--issuer)
  assoc certify-moderator    certifica a chave da moderação (--moderator)
  id create|show             identidade (chave pública do diário)
  cert add                   grava o certificado como bloco 0 do diário
  profile set                define nome e bio
  post                       publica um texto (--text)
  reply                      responde a uma publicação (--to <chave>:<seq> --text)
  delete                     apaga uma publicação ou versão do perfil (--to <chave>:<seq>)
  follow|unfollow|follows    segue ou deixa de seguir uma chave pública
  log                        mostra os blocos locais de um diário
  feed                       feed com as publicações dos diários seguidos
  sync                       sincroniza com pares e com o semeador (--once, --timeout-ms)
  seed                       semeador sempre ligado (--health-port, --ws-port)
  seed key|cert add          chave do semeador e seu certificado (--cert-file)
  seed list|status           diários admitidos e estado do semeador
  seed drop <chave>          apaga um diário do semeador parado
  account                    serviço de contas (celular, @nome, convites, denúncias) (--account-port, --account-host); páginas com VARANDA_PAGE_KEYS e VARANDA_SEEDER_WS, busca de GIF com VARANDA_GIF_API_URL e VARANDA_GIF_API_KEY (desligadas por padrão), prévia de links desligada com VARANDA_PREVIEW=0, música do Audius com VARANDA_AUDIUS_API_KEY (desligada por padrão)
  account key                chave do emissor do serviço de conta (imprime só a pública)
  account cert add           grava o certificado do emissor (--cert-file <f>)
  account push-key           chave dos avisos push da versão web (imprime só a pública)
  account status             estado do serviço de conta
  account export             exporta os vínculos de conta do serviço parado
  account reports            exporta as denúncias com os e-mails do vínculo (--member)
  account phone              mostra o celular verificado de um membro, para pedido judicial (--member)
  account phone --release    libera o celular de um membro por ordem judicial, com o serviço parado (--member)
  account phone --username   acha a conta que teve o nome, atual ou passada, e mostra o celular (página: dona, sem número)
  mod init|show              chave da moderação e estado da lista de bloqueio
  mod cert add               grava o certificado da moderação (--cert-file <f>)
  mod block|unblock <chave>  bloqueia ou desbloqueia uma conta e publica a lista
  mod revoke-issuer <chave>  revoga a chave de um emissor e publica a lista
  mod unrevoke-issuer        desfaz a revogação de um emissor (<chave>)
  mod publish                reenvia a lista gravada ao semeador (--seeder)
  mod apply                  revisa as decisões do painel, assina e publica (--server, --yes)
  group create               cria um grupo numa comunidade (--community, --name, --join open|approval, --private cifrado)
  group join|leave <chave>   entra no grupo (ou pede entrada) e sai dele (--community se o grupo ainda não chegou)
  group post <chave>         publica no grupo (--text)
  group read <chave>         lê o grupo, das mais novas (--limit, --before <at>,<escritor>,<seq>)
  group list                 grupos dos quais você participa
  group info|members|requests <chave>  dados do grupo, membros e pedidos de entrada
  group admit|ban|admin <chave>        modera um membro (--member, --undo desfaz)
  group hide <chave>         oculta uma mensagem (--to <escritor>:<seq>, --undo)
  group meta <chave>         muda nome ou entrada do grupo (--name, --join)
  group rekey <chave>        gera uma nova chave do grupo privado
  community create           cria uma comunidade com o grupo Geral (--name, --join open|approval)
  community join|leave <chave>         entra na comunidade (e no Geral) e sai dela
  community leave <chave> --force      quem criou sai sem esperar os grupos que ainda não chegaram
  community info|list        dados da comunidade e seus grupos; suas comunidades
  community members|requests <chave>   membros e pedidos de entrada da comunidade
  community admit|ban|admin <chave>    modera um membro da comunidade (--member, --undo)
  community meta <chave>     muda nome ou entrada da comunidade (--name, --join)
  community remove-group <chave> <grupo>  tira um grupo da lista da comunidade (quem criou, de volta após sair; --undo devolve)
  page register              registra o delegado de página deste nó (imprime só a chave pública)
  page terms                 aceita os Termos para o delegado no serviço de conta
  page create                cria uma página (--username, --name, --bio)
  page list                  páginas que você tem ou administra, convites e ofertas
  page post|reply            publica ou responde como a página (--page, --text, --to, --file até 10)
  page photo                 foto da página (--page, --file, --name, --bio)
  page follow|unfollow       a página segue ou deixa de seguir uma chave (--page, --key)
  page notices               avisos da página (--page, --limit)
  page close|move            encerra a página ou muda a sua chave (--page)
  page join|leave            a página entra ou sai (--page, --community ou --group)
  page group-post            a página publica num grupo (--page, --group, --text)
  secrets key                chave X25519 deste servidor para os segredos (--out; imprime só a pública)
  secrets signing-key        chave Ed25519 de quem sela (--out; imprime só a pública)
  secrets seal               sela e assina as credenciais compartilhadas (--file, --recipients, --signing-key, --seq, --out)
  secrets open               confere a assinatura e abre os segredos deste servidor (--key-file, --file, --signers, --out; sai com 3 se não for destinatário)
  secrets verify             confere a assinatura de um arquivo selado, sem chave secreta (--file, --signers)
  help                       esta ajuda
Opções globais:
  --data <dir>               diretório de dados (ou VARANDA_DATA, padrão ./data)
  --association <hex>        chave pública da associação (ou VARANDA_ASSOCIATION)
  --bootstrap <host:porta>   repetível (ou VARANDA_BOOTSTRAP, separado por vírgula)
  --dht-host <ip>            endereço local da DHT (ou VARANDA_DHT_HOST)
  --json                     saída JSON na última linha
  page: VARANDA_ACCOUNT_ORIGIN, origem https do serviço de conta
Opções dos comandos:
  --member --seeder --age-band --method --out --cert-file --name --bio --text
  --to --author --limit --before --once --timeout-ms --health-port --health-host --ws-port --ws-host
  --ws-origin --issuer --account-port --account-host --moderator --no-publish --new-list --server --yes
  --join --undo --private --community --force --no-dm --page --key --username --group --file --blob-bytes --release
  --recipients --key-file --signing-key --signers --seq
  --timeout-ms vai até 2147483647 ms. No assoc certify*, --out recusa arquivo existente e link simbólico.
  --blob-bytes: teto do conjunto de mídia das conversas no seed (bytes, padrão 4294967296).

--json coloca um objeto JSON na última linha da saída padrão. Em sync e seed, cada evento é uma linha JSON e o resultado fecha a saída. Nenhum comando imprime chave secreta. seed key imprime só a chave pública Noise do semeador.

Registros

O diário é uma sequência de blocos JSON. O índice do bloco é o seq, a partir de 0.

  • Bloco 0: { "type": "member-cert", "cert": <certificado> }. O campo cert.member é a chave pública do diário. Sem esse bloco o diário não recebe perfil, publicação nem resposta.
  • profile: nome (1 a 80 caracteres) e bio (0 a 280).
  • post: texto (1 a 1000 caracteres). Uma resposta é um post com replyTo apontando para <chave>:<seq> de outra publicação. O seq do alvo é um inteiro maior ou igual a 1, porque o bloco 0 é o certificado. Uma publicação pode ter media, até 10 fotos de um núcleo de fotos (só a versão web hospedada as grava); com fotos, o texto pode ficar vazio. A CLI mostra só [foto] ou [N fotos].
  • follow: follow e unfollow também gravam no diário um registro follow (on verdadeiro ou falso) quando o bloco 0 já existe. A lista de seguidos fica pública e chega igual a todos os aparelhos do membro.
  • media-core: declara um núcleo de fotos do diário.

log imprime uma linha por bloco: #<seq> certificado, #<seq> perfil <nome>, #<seq> publicação <texto>, #<seq> segue <8 hex>, #<seq> deixa de seguir <8 hex>, #<seq> mídia <8 hex> ou #<seq> inválido (<motivo>). Com --json, uma linha JSON por bloco e o resultado no fim, como antes. --limit <n> mostra só os últimos n blocos e --before <seq> os blocos de seq menor que o dado (um inteiro maior ou igual a 1, como em log.read); se sobram blocos mais antigos, log avisa na saída de erro (com --json, o resultado final traz next, o seq a passar em --before, ou null). Nós de antes dessa mudança pulam follow, media-core e a publicação com fotos inteira, sem recusar o diário.

O nome não leva caractere de controle (código menor que 0x20). Em bio e texto o único controle permitido é a quebra de linha (LF).

Certificado de membro

O certificado tem exatamente estas chaves: v (1), member (chave pública do diário), ageBand, method, date (ISO-8601 UTC canônico, com milissegundos), association (chave pública da associação) e signature (128 hex minúsculos).

Faixas sugeridas: 13-15, 16-17, 18+. O padrão de assoc certify é --age-band 18+ e --method stub. ageBand casa com /^[a-z0-9+-]{1,32}$/; method casa com /^[a-z0-9-]{1,32}$/.

A associação guarda, por membro, só a chave pública, a faixa etária, o método e a data (members.jsonl). Não guarda assinatura, chave secreta, imagem nem documento. Quem opera assoc certify afirma a faixa etária. A checagem de idade de um provedor real está fora desta fase (comentário TODO(phase1) em packages/core/lib/assoc.js).

Certificado de semeador

O certificado do semeador tem exatamente estas chaves: v (1), seeder (chave pública Noise, a mesma que seed key imprime), date, association e signature. O prefixo assinado é varanda-seeder-v1, diferente de varanda-cert-v1. Uma assinatura de membro não valida certificado de semeador, e uma assinatura de semeador não valida certificado de membro.

A associação registra em seeders.jsonl só a chave do semeador e a data. Sem assinatura e sem segredo.

Semeador e admissão

O semeador fica ligado, no tópico da associação, e replica os diários que admitiu. Na entrada ele confere o bloco 0. Diário com certificado de outra associação, certificado malformado, bloco 0 inválido ou histórico reescrito (fork) é recusado.

No sync, um par só conta como semeador verificado quando o hello traz papel seeder, o certificado confere com a chave Noise autenticada da conexão e a associação é a raiz fixada em config.json. O resultado admitted: true exige esse semeador verificado. Um par que se diz semeador sem esse certificado aparece como peer seeder <8 hex> não verificado. O admitted desse par não é impresso e não marca o diário como admitido. Um rejected para o próprio diário vindo de qualquer par que não seja semeador verificado vira a linha withdrawn <chave> <8 hex do par> <motivo> e não decide o sucesso do sync.

sync --once sai com código 0 quando ao menos um par enviou hello, nenhum diário seguido ficou atrás do tamanho que um par anunciou, os pares interessados no próprio diário alcançaram o tamanho dele e, se há semeador verificado e o bloco 0 local é um certificado válido, um semeador verificado enviou admitted até esse tamanho. O prazo padrão é 30000 ms (--timeout-ms, no máximo 2147483647; acima disso o comando sai com erro de uso, código 2).

Tópico por associação

Membros e semeadores da mesma associação se encontram num tópico de rendezvous derivado da chave pública dessa associação (varanda/rendezvous/v1: + hex). Cada um também anuncia a chave de descoberta dos diários que guarda.

Raiz de confiança

Cada diretório confia numa única chave pública de associação, gravada em config.json e imutável depois.

  • Membro: id create exige --association <hex> ou VARANDA_ASSOCIATION na primeira vez e grava { "v": 1, "role": "member", "association": "<hex64>" }. Rodar de novo devolve a mesma chave pública do diário.
  • Semeador: o primeiro entre seed key, seed cert add e seed grava { "v": 1, "role": "seeder", "association": "<hex64>" }. Sem associação nessa primeira vez o uso é informe --association ou VARANDA_ASSOCIATION (código 2).

Num comando seguinte, --association e VARANDA_ASSOCIATION são opcionais. Se vierem, têm de ser o valor já gravado. Caso contrário o erro é associação diferente da configurada (código 1). O nó não escolhe a raiz lendo um certificado recebido.

assoc show --data <dir> e id show --data <dir> imprimem de novo a chave pública. id show sem identidade termina com erro: identidade não encontrada.

Variáveis de ambiente

Variável Função
VARANDA_DATA Diretório de dados. Padrão ./data. O passo a passo usa --data no lugar dela.
VARANDA_ASSOCIATION Chave pública da associação (64 hex, qualquer caixa; gravada em minúsculas).
VARANDA_BOOTSTRAP Nós host:porta separados por vírgula. Ausente, e sem --bootstrap, os comandos usam a DHT pública.
VARANDA_DHT_HOST Endereço local em que a DHT deste processo escuta. O mesmo que --dht-host.
VARANDA_HEALTH_PORT Porta do endpoint de saúde do seed. O mesmo que --health-port. Ausente, não há endpoint.
VARANDA_HEALTH_HOST Endereço do endpoint de saúde. O mesmo que --health-host. Padrão 127.0.0.1.
VARANDA_WS_PORT Porta da entrada WebSocket do seed. O mesmo que --ws-port. Ausente, nada escuta.
VARANDA_WS_HOST Endereço da entrada WebSocket. O mesmo que --ws-host. Padrão 127.0.0.1.
VARANDA_WS_ORIGIN Origens de navegador aceitas na entrada WebSocket, separadas por vírgula (ex.: https://app.exemplo.org). O mesmo que --ws-origin (repetível). Ausente, só páginas http em loopback.
VARANDA_MAX_MEMBERS Teto de contas vinculadas no serviço account (em deploy/seeder/.env), de 1 a 4096. Ausente ou vazio, sem teto. Ao chegar ao teto, um vínculo novo recebe "lista de espera" (HTTP 503); quem já é membro não muda. O app hospedado pergunta GET /account/admission antes de criar uma passkey. Ver "Vínculo de conta Google e @nome".
VARANDA_INVITES_PER_WEEK Convites por membro e por semana, de 1 a 100 (em deploy/seeder/.env; reiniciar o serviço account para mudar). Ausente ou vazio, o cadastro não exige convite, mas continua sujeito a VARANDA_MAX_MEMBERS e às verificações de idade e celular. Definido, um vínculo novo só termina com um convite válido e cada membro vinculado ganha esse número de convites por semana civil de Brasília. Remover a variável desliga tudo: o invites.json fica no disco e é ignorado pelo serviço (o account status ainda mostra as contagens). Ver "Convites", em "Vínculo de conta Google e @nome".
VARANDA_INVITE_DROPS Convites de surpresa (em deploy/seeder/.env; reiniciar o serviço account para mudar). Ausente ou vazio, desligado: os convites da semana abrem todos na segunda, como hoje. 1 liga: cada convite da semana abre num horário sorteado. Exige VARANDA_INVITES_PER_WEEK (o deploy.sh e o serviço recusam o par incompleto). Não há limiar automático de membros: o operador liga quando a rede chegar perto de 500. Ver "Convites", "Convites de surpresa".
VARANDA_FEIRA_INVITES_PER_WEEK Cadastros por semana de cada dono pelo link de um anúncio da Feira, de 1 a 100 (em deploy/seeder/.env; reiniciar o serviço account para mudar; 10 é só um exemplo do operador). Ausente ou vazio, desligado. Exige VARANDA_INVITES_PER_WEEK e VARANDA_TRIAGE_TOKEN (o deploy.sh e o serviço recusam o conjunto incompleto).
VARANDA_FEIRA_ORIGIN Origem https das páginas públicas da Feira (em deploy/seeder/.env; minúsculas, sem caminho, por exemplo https://varanda.example). O compose.web.yaml a passa ao semeador como VARANDA_PUBLIC_ORIGIN; fora do compose, o semeador lê VARANDA_PUBLIC_ORIGIN direto. Ausente ou vazia (o padrão), as rotas /f/* e /index/feira/* do semeador respondem 404. O deploy.sh recusa um valor que não seja uma origem https.
VARANDA_PUBLIC_ORIGIN (semeador) Mesma origem acima, lida pelo varanda seed (sem opção de linha de comando; o --help não muda). Opcional e validada: uma origem https em minúsculas, sem caminho. No serviço account a mesma variável tem outro papel (o domínio público do serviço) e o compose.web.yaml a mantém como está.
VARANDA_POSTS_ORIGIN Origem https das páginas públicas de publicação, um aperitivo para quem está fora da Varanda (em deploy/seeder/.env, que o compose.web.yaml passa ao semeador com o mesmo nome; fora do compose, o varanda seed a lê direto). Mesma regra de VARANDA_PUBLIC_ORIGIN: uma origem https em minúsculas, sem caminho; o varanda seed e o deploy.sh recusam outro valor. Sem opção de linha de comando (o --help não muda). Independente da Feira: VARANDA_FEIRA_ORIGIN não a liga, e ela não liga a Feira. Ausente ou vazia (o padrão), a página /p/<diário>/<seq> redireciona para o app (/publicacao/<diário>/<seq>), as fotos respondem 404 e /p/policy diz que as páginas estão desligadas. Deixe a variável vazia até a instalação estar nos Termos versão 48 e o operador decidir quem pode publicar.
VARANDA_DIDIT_API_KEY Chave da API do Didit para a verificação de idade (em deploy/seeder/.env; só o serviço account a recebe; reiniciar para mudar). Segredo. Vazia junto com VARANDA_DIDIT_WORKFLOW_ID, a checagem fica desligada. Ver "Verificação de idade (Didit)".
VARANDA_DIDIT_WORKFLOW_ID Id do workflow do Didit (idade por rosto, com documento de reserva). Chave e id definidos ligam a checagem para todo membro hospedado, inclusive quem já está vinculado; só um dos dois é erro de uso.
VARANDA_DIDIT_DAILY_LIMIT Teto de sessões novas no Didit por dia (padrão: 200), contado à parte para chaves sem vínculo e para membros já vinculados. Opcional.
VARANDA_AGE_SINCE O momento em que a verificação de idade passou a valer nesta instalação, em ISO (2026-10-29T00:00:00.000Z), nunca antes. Exige a checagem ligada (VARANDA_DIDIT_API_KEY e VARANDA_DIDIT_WORKFLOW_ID): sem elas o serviço não sobe. GET /account/age/since responde { since } com um atestado assinado na hora pelo emissor (o mesmo vale por no máximo um minuto), datado do momento da assinatura, e { since:null } enquanto não houver faixa registrada ou o serviço não tiver certificado de emissor. O since servido nunca é anterior a esse momento, ao início do dia UTC seguinte à primeira faixa registrada, nem à última vez em que a checagem foi ligada (guardada em age-check.json, no diretório de dados), nem ao certificado mais recente de um membro vinculado sem faixa registrada. O app guarda o atestado no nó, que confere a assinatura a cada leitura, e libera direto, em qualquer aparelho, a conta cujo certificado tem data entre o since e a data do atestado, porque com a checagem ligada o serviço não emite certificado sem faixa de idade registrada. Um atestado só vale para certificados datados até a sua assinatura. Se age-check.json estiver inválido, a rota responde 503 indisponivel até a operação corrigir o arquivo ou restaurar a cópia mais recente; se o serviço não conseguir gravá-lo ao subir com a checagem desligada, ele não sobe. GET /account/age/policy continua respondendo só { required }. Se a checagem for desligada, remova a variável; ao religar, use o novo momento (o serviço já não serve nada anterior ao religamento). Vazia, a rota responde { since:null }; valor fora desse formato impede o serviço de subir. Opcional.
VARANDA_PHONE_KEY Chave da verificação de celular (em deploy/seeder/.env; só o serviço account a recebe; reiniciar para mudar): 64 caracteres hexadecimais minúsculos, gerados com openssl rand -hex 32. Segredo. Vazia, a verificação fica desligada. Definida, sela os números e o índice do phone.json e exige a verificação de idade ligada (VARANDA_DIDIT_API_KEY e VARANDA_DIDIT_WORKFLOW_ID); fora do formato, o serviço não sobe e a mensagem nunca repete o valor. Ver "Verificação de celular (serviço account)" antes de definir.
VARANDA_PHONE_DAILY_LIMIT Teto de envios de código por dia, inteiro de 1 a 100000 (padrão: 200; fora disso o serviço se recusa a subir), contado à parte para chaves vinculadas e para chaves ainda sem vínculo. Lida só com VARANDA_PHONE_KEY definida. Opcional.
VARANDA_ACCOUNT_MAX_CONNECTIONS Conexões simultâneas do serviço account, de 1 a 4096. Padrão 64.
VARANDA_ACCOUNT_RATE Requisições por segundo do balde global do serviço account, de 1 a 10000. Padrão 20.
VARANDA_ACCOUNT_BURST Rajada permitida acima da taxa no balde global do serviço account, de 1 a 100000. Padrão 100.
VARANDA_ACCOUNT_MAX_PENDING Vínculos pendentes ao mesmo tempo no serviço account, de 1 a 100000. Padrão 1000.
VARANDA_PUSH_TOKEN Segredo do POST /push-event entre o semeador e o serviço de conta: 64 hex minúsculos, o mesmo valor nos dois (openssl rand -hex 32). Vazio ou ausente desliga os avisos push (a rota responde 404). Em deploy/seeder/.env. O erro de formato não repete o valor (uso: VARANDA_PUSH_TOKEN inválido).
VARANDA_PAGE_KEYS Chave de custódia das páginas (empresas e projetos) no serviço account: 64 hex minúsculos (openssl rand -hex 32), em deploy/seeder/.env, só o serviço account a recebe (reiniciar para mudar). Vazia ou ausente, as páginas ficam desligadas. Malformada, o serviço recusa subir e o erro nunca repete o valor. Ver "Páginas", no operador.
VARANDA_SEEDER_WS URL WebSocket de loopback do semeador onde o escritor das páginas se liga, ws://127.0.0.1:<porta> (a porta de VARANDA_WS_PORT, sem o /seeder, que é acrescentado). Obrigatória com VARANDA_PAGE_KEYS: ausente ou fora de loopback, o serviço recusa subir. Ignorada com as páginas desligadas.
VARANDA_GIF_API_URL Endereço base da API de busca do provedor de GIFs, no formato de busca compatível com o Giphy (<base>/gifs/search), no serviço account (em deploy/seeder/.env; reiniciar para mudar). Só https, sem usuário, consulta nem endereço IP. Vem junto com VARANDA_GIF_API_KEY: as duas vazias ou ausentes deixam a busca de GIFs desligada (GET /account/gif/policy responde { "enabled": false } e as outras rotas /account/gif/*, 404 feature-off); só uma das duas, ou um valor malformado, faz o serviço recusar subir, sem repetir o valor.
VARANDA_GIF_API_KEY Chave da API do provedor de GIFs. Segredo: só o serviço account a recebe, ela vai só para o provedor e nunca aparece em registro, resposta ou erro. Vem junto com VARANDA_GIF_API_URL.
VARANDA_GIF_MEDIA_HOSTS Opcional. Nomes de host (exatos, separados por vírgula, nunca IP) de onde o provedor serve as imagens, além do host da API. O serviço só baixa miniaturas e GIFs em https nesses hosts, resolvidos só para endereços públicos. Malformada, o serviço recusa subir.
VARANDA_AUDIUS_API_KEY Chave da API do Audius, que liga a música no serviço account: busca, trechos nas publicações e faixas e playlists tocadas no player do Varanda (em deploy/seeder/.env; reiniciar para mudar). Vazia ou ausente, a música fica desligada. Segredo: só o serviço account a recebe, ela vai só para o Audius (num cabeçalho, nunca na URL) e nunca aparece em registro, resposta ou erro. O áudio passa pelo serviço account, que usa a banda e os sockets do servidor. Nunca defina a chave numa instalação cuja versão dos Termos seja menor que 39. Malformada, o serviço recusa subir sem repetir o valor.
VARANDA_AUDIUS_API_URL Opcional. Endereço base da API do Audius. Padrão https://api.audius.co/v1. Só https, sem usuário, consulta nem endereço IP. Definida com a chave vazia, ou malformada, o serviço recusa subir.
VARANDA_AUDIUS_APP_NAME Opcional. Nome do app que o Audius pede em cada consulta (público): letras minúsculas, números e hífen, até 32. Padrão varanda. Definida com a chave vazia, ou malformada, o serviço recusa subir.
VARANDA_AUDIUS_MOMENTS Opcional. 1 liga a música nos momentos; ausente, vazia ou 0 deixa desligada. Fica desligada até o Audius confirmar por escrito que permite esse uso. Outro valor, ou definida com a chave vazia, faz o serviço recusar subir (uso: VARANDA_AUDIUS_MOMENTS inválido: use 0 ou 1). Ordem de lançamento do registro com música: semeadores, a web hospedada, os apps, e só então este interruptor. Quem lê num build anterior (app, web, CLI ou semeador) não vê um momento que leva música: o registro de cinco chaves é pulado como malformado, e o diário não é rejeitado.
VARANDA_AUDIUS_COVERS Opcional. 1 liga as capas de música do Audius; ausente, vazia ou 0 deixa desligada. Outro valor faz o serviço recusar subir (uso: VARANDA_AUDIUS_COVERS inválido: use 0 ou 1). Definida com a chave da API vazia, o serviço recusa subir sem repetir o valor (uso: VARANDA_AUDIUS_API_KEY ausente). Nunca definir VARANDA_AUDIUS_COVERS=1 antes de a versão dos Termos que descreve as capas estar instalada. Se a confirmação por escrito do Audius também é exigida, isso fica pendente da decisão de quem é dono do projeto.
VARANDA_AUDIUS_STREAMS Opcional. Áudios do Audius que o serviço account repassa ao mesmo tempo, de 1 a 32. Padrão 16. Cada um ocupa banda e um socket do servidor enquanto toca. Definida com a chave vazia, ou fora do intervalo, o serviço recusa subir.
VARANDA_PREVIEW Prévia de links no serviço account (em deploy/seeder/.env; reiniciar para mudar). Não precisa de chave de terceiros, então fica ligada por padrão: ausente, vazia ou 1 liga, 0 desliga (GET /account/preview/policy responde { "enabled": false } e as outras rotas /account/preview/*, 404 feature-off). Outro valor faz o serviço recusar subir (uso: VARANDA_PREVIEW inválido: use 0 ou 1).
VARANDA_ACCOUNT_HTTP Onde o semeador alcança o HTTP do serviço de conta. Padrão http://127.0.0.1:8790. Só HTTP em loopback (127.0.0.1, localhost ou [::1]), com porta explícita. Outra forma é uso: VARANDA_ACCOUNT_HTTP inválido.
VARANDA_MAX_EXTERNAL Conexões externas (WebSocket) que o seed aceita ao mesmo tempo, de 1 a 4096. Padrão 32, independente do limite do enxame. Cada aba visível da web hospedada e cada app instalado aberto em primeiro plano mantêm uma conexão enquanto estiverem visíveis: dimensione para as abas e os apps abertos ao mesmo tempo mais folga para os links curtos da Espiadinha e dos Avisos (apps/cli/scripts/load-ws.js mede conexões seguradas). No pior caso cada uma segura até 8 MiB de quadro: a memória fica em ≈ VARANDA_MAX_EXTERNAL × 8 MiB + VARANDA_FRAME_MEMORY.
VARANDA_FRAME_MEMORY Memória total, em bytes, para quadros grandes em montagem no seed, de 8454144 (8 MiB + 64 KiB, o maior quadro válido) a 1073741824 (1 GiB). Padrão 64 MiB. Some à regra de memória: ≈ VARANDA_MAX_EXTERNAL × 8 MiB + VARANDA_FRAME_MEMORY no pior caso.
VARANDA_MAX_SOCKETS Sockets abertos ao mesmo tempo na porta do --ws-port (WebSocket, /media, /index e conexões mantidas pelo proxy), de 1 a 8192. Padrão: externas + /media + /index em andamento + 64, ao menos 128.
VARANDA_MEDIA_MAX_IN_FLIGHT Respostas de /media em andamento ao mesmo tempo, de 1 a 1024. Padrão 16.
VARANDA_MEDIA_RATE Pedidos de /media por segundo, de 1 a 100000. Padrão 64.
VARANDA_MEDIA_BURST Rajada de pedidos de /media, de 1 a 100000. Padrão 128.
VARANDA_INDEX_MAX_IN_FLIGHT Respostas de /index em andamento ao mesmo tempo, de 1 a 1024. Padrão 16.
VARANDA_INDEX_RATE Pedidos de /index por segundo, de 1 a 100000. Padrão 32.
VARANDA_INDEX_BURST Rajada de pedidos de /index, de 1 a 100000. Padrão 64.

A Feira, quando ligada, publica anúncios em páginas públicas do semeador: GET|HEAD /f/<diário>/<seq>, as fotos em /f/<diário>/<seq>/foto/<n> e /f/sitemap.xml. As páginas são públicas, saem com Cache-Control: no-store e podem ser indexadas por buscadores. O Caddy repassa só /f/* ao semeador (30 pedidos por 10 s por endereço, sem repassar o endereço do cliente) e serve um /robots.txt que permite apenas /f/ (e /p/, das páginas de publicação abaixo) e aponta o sitemap em https://<domínio>/f/sitemap.xml; o resto do site fica fora dos buscadores. O service worker nunca intercepta /f/*. As rotas de moderação do semeador (/moderation-listing, /moderation-post) e a conferência da entrada (/feira-listing, com orçamento próprio no semeador) nunca passam pelo Caddy. A entrada por link (/account/feira/*) tem limite de 5 pedidos por 60 s por endereço no Caddy (zona feira-entrada) e um teto global de 60 por 60 s (zona feira-entrada-total, contra a troca de endereço IPv6), e as sessões pagas de idade com código da Feira têm tetos próprios: 1 por código por dia e 50 por dia para todos os códigos da Feira (sem teto por dono, que qualquer um poderia gastar para trancar um vendedor), fora do teto diário dos cadastros comuns. Essas sessões só abrem por POST /account/feira/idade (mesmo corpo de POST /account/age/session, que recusa um código da Feira com use-a-rota-da-feira; um código comum na rota da Feira recebe pedido-invalido), e o Caddy limita essa rota a 2 pedidos por hora por endereço (zona feira-idade) e 50 por hora no total (zona feira-idade-total). O serviço continua sem ler endereço. Resíduo: quem troca de endereço IPv6 dentro de um /64 chega só aos tetos globais e ainda pode parar os cadastros pela Feira no dia, nunca os comuns; atrás de CGNAT, quem divide um endereço pode ver o limite. Ative só depois do PR 4 da Feira (o app) e dos Termos versão 28 estarem no ar: deixe VARANDA_FEIRA_ORIGIN vazia até lá.

As páginas públicas de publicação, quando ligadas (VARANDA_POSTS_ORIGIN), ficam no semeador em GET|HEAD /p/<diário>/<seq>, com as fotos em /p/<diário>/<seq>/foto/<n>, a prévia em /p/<diário>/<seq>/previa (JSON, para o app mostrar a publicação antes da entrada) e /p/policy (diz ao app se as páginas estão ligadas), sem sitemap. O Caddy repassa /p/* ao semeador numa zona própria (publicacao, 30 pedidos por 10 s por endereço, separada da zona da Feira), sem repassar o endereço do cliente, e o /robots.txt traz Allow: /p/ só para que os buscadores leiam o noindex de cada página. O service worker nunca intercepta /p/*. Desligadas, cada página redireciona para o app (/publicacao/<diário>/<seq>) e /p/policy diz que estão desligadas. Deixe VARANDA_POSTS_ORIGIN vazia até os Termos versão 48 estarem na instalação e o operador decidir quem pode publicar.

As variáveis de limite do semeador (VARANDA_MAX_EXTERNAL até VARANDA_INDEX_BURST) não têm opção de linha de comando. Vazias contam como ausentes; um valor fora do intervalo ou que não seja um inteiro decimal termina com uso: VARANDA_<NOME> inválido (código 2), sem repetir o valor.

--bootstrap pode repetir. Se algum --bootstrap aparece na linha, ele prevalece sobre VARANDA_BOOTSTRAP. --dht-host prevalece sobre VARANDA_DHT_HOST.

Um VARANDA_BOOTSTRAP vazio ou malformado é erro de uso e não cai na DHT pública. Exemplos: uso: bootstrap inválido (vazio), uso: bootstrap inválido localhost. A porta não leva zero à esquerda; o formato é host:porta com porta de 1 a 65535.

VARANDA_DHT_HOST e --dht-host aceitam uma string não vazia e sem espaço. Qualquer outro valor termina com uso: dht-host inválido.

VARANDA_HEALTH_PORT e --health-port aceitam um número de 0 a 65535, sem zero à esquerda (0 deixa o sistema escolher a porta); senão uso: health-port inválido. VARANDA_HEALTH_HOST e --health-host seguem a regra do --dht-host (uso: health-host inválido). A opção prevalece sobre a variável. Detalhes em "Operar o semeador".

VARANDA_WS_PORT e --ws-port seguem a regra do --health-port (uso: ws-port inválido); VARANDA_WS_HOST e --ws-host seguem a do --dht-host (uso: ws-host inválido). Cada origem de --ws-origin / VARANDA_WS_ORIGIN é escrita exatamente como o navegador a envia: http ou https, host e porta só se não for a padrão, sem caminho nem barra no fim; outra forma é uso: ws-origin inválido <valor>, e uma lista vazia é uso: ws-origin inválido (vazio). Qualquer --ws-origin vale mais que a variável.

A DHT local de apps/cli/scripts/local-dht.js escuta só em 127.0.0.1. Com ela, defina VARANDA_DHT_HOST=127.0.0.1 ou passe --dht-host 127.0.0.1. Testes e npm run demo usam esse endereço. Sem bootstrap (DHT pública, uso manual), o endereço local é opcional e a DHT fica nos padrões da biblioteca.

Um processo por diretório de dados

store/ é um Corestore em RocksDB e segura um lock do sistema. Antes de abri-lo, o varanda também cria o lock <dir>/.varanda-lock (com o pid do processo). Um segundo processo no mesmo --data falha com erro: diretório de dados em uso enquanto o primeiro não fecha o store; um lock deixado por um processo que morreu é retomado sozinho. Um lock com o pid do próprio processo que ele não pegou também é retomado: é o caso de um contêiner reiniciado, em que o semeador é sempre o pid 1. Um lock sem pid legível só é retomado quando o diretório do lock tem mais de 10 segundos. Se .varanda-lock não for um diretório (um arquivo ou um link simbólico), a abertura falha na hora com erro: lock inválido (não é um diretório): <caminho>; um link simbólico em <dir>/store também é recusado. Se o pid de um processo morto foi reaproveitado por outro processo seu, o lock continua em uso: confira que nenhum processo varanda usa o diretório e apague <dir>/.varanda-lock à mão. Comandos curtos abrem e fecham. sync e seed seguram o diretório o tempo todo em que estão rodando. seed status nunca pega o lock.

O store principal abre antes de quarantine/ ser apagado. O segundo processo esbarra no lock e não apaga a quarentena de um sync ou seed que já está de pé.

Não misture papéis no mesmo diretório. Comando de membro em diretório de semeador: diretório não é de um membro. Comando de semeador em diretório de membro: diretório não é de um semeador.

Publicação no futuro e diário reescrito

Uma publicação válida cuja data at está mais de 24 horas à frente do relógio de quem lê (MAX_FUTURE_MS = 86400000 em packages/core/lib/feed.js) fica de fora do feed. O comando avisa em stderr aviso: publicação <chave>:<seq> ignorada (future). Ela volta sozinha quando o relógio do leitor chega em at menos 24 horas. Publicação no passado permanece e afunda na ordem (at, autor, seq). O corte é pular, não redatar: redatar mudaria a posição em cada leitor e em cada execução.

Nenhum escritor desta fase trunca o diário. Se fork deixa de ser zero, o detentor da chave reescreveu o histórico. Esse diário é descartado em todo lugar, motivo fork: o semeador para de servi-lo, o sync apaga a réplica e o feed avisa aviso: diário <8 hex> ignorado (fork). O feed só lê; o próximo sync é que apaga a cópia local.

Passo a passo manual

Dois diários (Alice e Bob) e um semeador, na mesma máquina, em diretórios novos:

  • data/assoc — associação de teste
  • data/seeder — semeador
  • data/alice — diário da Alice
  • data/bob — diário do Bob
  • data/certs — JSON dos certificados (--out / --cert-file); --out só grava arquivo novo (recusa arquivo existente e link simbólico, código 1): apague o antigo antes de emitir de novo; não é um diretório de papel

Rode tudo na raiz do repositório, em bash ou zsh (as linhas com $(...) e ${var##padrão} dependem disso). data/ está no .gitignore. Se esses diretórios já existem de uma tentativa anterior, use outros caminhos ou apague-os antes: assoc init recusa uma associação já criada, e cert add recusa um bloco 0 diferente do que já está no diário.

Cada comando deve terminar com código 0 antes do próximo. A chave secreta da associação fica em data/assoc/association.json (modo 0600). A chave secreta Noise do semeador fica em data/seeder/seeder-key.json (modo 0600). Nenhum comando as imprime. Não as copie para o terminal.

1. DHT local, ou a DHT pública

DHT local (um computador, sem a DHT pública). Num terminal, deixe rodando:

node apps/cli/scripts/local-dht.js

A porta padrão é 49737 (node apps/cli/scripts/local-dht.js --port 49800 escolhe outra). O processo escuta só em 127.0.0.1 e imprime uma linha export VARANDA_BOOTSTRAP=127.0.0.1:<porta>. Ctrl-C encerra.

Nos outros terminais, use a linha impressa e o endereço local. Com a porta padrão:

export VARANDA_BOOTSTRAP=127.0.0.1:49737
export VARANDA_DHT_HOST=127.0.0.1

DHT pública. Não inicie apps/cli/scripts/local-dht.js e deixe VARANDA_BOOTSTRAP e VARANDA_DHT_HOST sem definir (unset VARANDA_BOOTSTRAP VARANDA_DHT_HOST: um VARANDA_DHT_HOST=127.0.0.1 que sobrou da DHT local prenderia a DHT ao loopback, longe dos pares públicos). Os comandos usam a DHT pública. Não passe --bootstrap nem --dht-host. Nas linhas de seed e sync abaixo, apague --bootstrap "$VARANDA_BOOTSTRAP" --dht-host "$VARANDA_DHT_HOST".

2. Associação

line=$(node bin/varanda.js assoc init --data data/assoc)
printf '%s\n' "$line"
ASSOC=${line##* }

A linha é chave pública da associação: seguida de 64 hex. $ASSOC é essa chave.

3. Chave do semeador, certificado, depois o processo

seed key cria data/seeder, grava a raiz de confiança e cria seeder-key.json se ele ainda não existe. Na segunda vez devolve a mesma chave pública.

line=$(node bin/varanda.js seed key --data data/seeder --association "$ASSOC")
printf '%s\n' "$line"
SEEDER=${line##* }

A linha é chave do semeador: seguida de 64 hex.

mkdir -p data/certs
node bin/varanda.js assoc certify-seeder --data data/assoc --seeder "$SEEDER" --out data/certs/seeder.json
node bin/varanda.js seed cert add --data data/seeder --association "$ASSOC" --cert-file data/certs/seeder.json

A primeira imprime certificado do semeador gravado em <caminho absoluto>. A segunda imprime certificado do semeador gravado. Sem --seeder o uso é uso: informe --seeder <hex>. Sem --cert-file o uso é uso: informe --cert-file <arquivo>.

Noutro terminal, com as mesmas variáveis VARANDA_BOOTSTRAP, VARANDA_DHT_HOST e ASSOC, deixe o semeador ligado:

node bin/varanda.js seed --data data/seeder --association "$ASSOC" --bootstrap "$VARANDA_BOOTSTRAP" --dht-host "$VARANDA_DHT_HOST"

Espere seed ready. Esse processo segura data/seeder até Ctrl-C, e então sai com código 0. Não rode outro comando com --data data/seeder enquanto ele estiver no ar.

seed sem seeder-key.json sai 1 com erro: chave do semeador não encontrada (use seed key). Sem seeder-cert.json: erro: certificado do semeador não encontrado (use seed cert add). Certificado que não bate com a chave ou com a associação: erro: certificado do semeador inválido (<motivo>). Esses três erros acontecem antes de qualquer rede.

4. Alice e Bob

line=$(node bin/varanda.js id create --data data/alice --association "$ASSOC")
printf '%s\n' "$line"
ALICE=${line##* }

line=$(node bin/varanda.js id create --data data/bob --association "$ASSOC")
printf '%s\n' "$line"
BOB=${line##* }

Cada linha é chave pública: seguida da chave do diário. Essa chave é a identidade. Repetir id create no mesmo diretório imprime a mesma chave.

node bin/varanda.js assoc certify --data data/assoc --member "$ALICE" --age-band '18+' --method stub --out data/certs/alice.json
node bin/varanda.js assoc certify --data data/assoc --member "$BOB" --age-band '18+' --method stub --out data/certs/bob.json
node bin/varanda.js cert add --data data/alice --cert-file data/certs/alice.json
node bin/varanda.js cert add --data data/bob --cert-file data/certs/bob.json

cert add imprime certificado gravado (bloco 0). O certificado tem de ser desta chave e desta associação. Um certificado de outra associação falha com certificado inválido (untrusted-association) (código 1).

node bin/varanda.js profile set --data data/alice --name 'Alice' --bio 'protótipo'
line=$(node bin/varanda.js post --data data/alice --text 'primeira publicação')
printf '%s\n' "$line"
SEQ=${line##*#}
printf '%s\n' "$ALICE:$SEQ"

profile set imprime perfil atualizado #<seq>. post imprime publicado #<seq>. $SEQ é esse número (inteiro maior ou igual a 1). Perfil, publicação e resposta exigem o bloco 0; sem ele a mensagem é erro: grave o certificado de membro antes de publicar.

5. Alice sincroniza e sai

node bin/varanda.js sync --data data/alice --once --timeout-ms 30000 --bootstrap "$VARANDA_BOOTSTRAP" --dht-host "$VARANDA_DHT_HOST"

A saída passa por sync ready, peer seeder <8 hex> e admitted <chave da Alice> <tamanho>, e fecha com sync done (código 0). O processo da Alice termina aí. O semeador permanece com a cópia.

Bob recebe a publicação por esse semeador com o sync da Alice já encerrado. A cópia está em data/seeder (admitted.json e store/). Parar o semeador com Ctrl-C (código 0) e subir de novo o mesmo comando seed, no mesmo diretório, continua servindo o diário depois de seed ready. É o que a demo automática confere. Os comandos abaixo valem para o processo que já imprimiu seed ready, seja o original, seja o que subiu do disco.

Sem par até o prazo, sync imprime sync failed: sem pares ou sync failed: tempo esgotado: ... e sai com código 1. Confira o terminal do semeador e o VARANDA_BOOTSTRAP / --dht-host.

6. Bob segue, sincroniza, lê e responde

node bin/varanda.js follow --data data/bob --author "$ALICE"
node bin/varanda.js sync --data data/bob --once --timeout-ms 30000 --bootstrap "$VARANDA_BOOTSTRAP" --dht-host "$VARANDA_DHT_HOST"
node bin/varanda.js feed --data data/bob

follow imprime seguindo e a chave da Alice, e grava no diário do Bob o registro follow (o Bob já tem o bloco 0). O sync do Bob baixa o diário dela pelo semeador (downloaded <chave da Alice> <tamanho>) e termina com sync done. feed lista a publicação, no formato [<data>] Alice (<8 hex>) #<seq> e o texto na linha seguinte. feed não abre a rede.

node bin/varanda.js reply --data data/bob --to "$ALICE:$SEQ" --text 'também li'
node bin/varanda.js sync --data data/bob --once --timeout-ms 30000 --bootstrap "$VARANDA_BOOTSTRAP" --dht-host "$VARANDA_DHT_HOST"

reply imprime publicado #<seq>. O segundo sync entrega a resposta ao semeador. --to é <64 hex>:<seq> com seq maior ou igual a 1, sem zero à esquerda. Fora isso o uso é referência inválida.

Para encerrar: Ctrl-C no semeador (código 0) e Ctrl-C na DHT local.

7. Grupos públicos

group create --community <comunidade> --name <nome> --join open|approval cria um grupo público e imprime grupo criado: <chave>; a chave é a raiz do grupo. Os demais subcomandos recebem a chave logo depois do nome: group join|leave <chave>, group post <chave> --text <texto>, group list, group info|members|requests <chave>, group admit|ban|admin <chave> --member <chave> (com --undo desfaz), group hide <chave> --to <escritor>:<seq> (com --undo mostra de novo) e group meta <chave> com --name e --join.

group read <chave> imprime uma linha por mensagem, das mais novas para as mais antigas: <at> <nome|@usuário|8 hex>: <texto>, ou (mensagem oculta). Com --limit <n> (até 31) e se há mais antigas, a última linha é mais antigas: --before <at>,<escritor>,<seq>. Com --json, a última linha é o resultado. Um pedido que altera estado nunca é reenviado: se o resultado for incerto, o erro avisa.

Comunidades contêm grupos públicos ou privados. community create --name <nome> --join open|approval cria a comunidade com o grupo Geral e imprime comunidade criada: <comunidade> e grupo Geral: <grupo>. Entre primeiro na comunidade com community join <chave>, que também entra no Geral ou pede entrada, e depois nos demais grupos com group join <chave>. Se o grupo ainda não chegou, informe --community <comunidade>. Só quem criou a comunidade cria grupos nela, pelo aparelho que a criou; os administradores moderam, mas não criam grupos. community leave <chave> encerra a participação na comunidade e nos seus grupos; quem criou a comunidade espera os grupos que criou chegarem ao aparelho, e --force sai sem esperar (nesses grupos, o que fez como criador antes deixa de valer). community admin <comunidade> --member <diário> (só quem criou a comunidade, --undo retira) nomeia um membro administrador da comunidade e de seus grupos. community info <chave> mostra os grupos e community list lista suas comunidades. community members|requests <chave> lista membros ou pedidos; community admit|ban <chave> --member <diário> modera um membro (--undo desfaz); community meta <chave> muda nome ou entrada com --name e --join. community remove-group <chave> <grupo> tira um grupo da lista da comunidade (só quem criou, de volta depois de sair; o Geral não sai), e com --undo o devolve, imprimindo grupo devolvido à lista da comunidade. Detalhes em docs/protocol.md §10.

Grupos privados são cifrados de ponta a ponta. group create --community <comunidade> --private --name <nome> imprime grupo privado criado: <chave>; a entrada é sempre por aprovação (--join open é recusado) e o nome viaja cifrado. Quem entra só lê depois que um administrador admite (group admit), e aí recebe também as chaves antigas. Banir, sair ou perder a administração gera uma chave nova que não vai para quem saiu; group rekey <chave> gera uma chave nova à mão. group read avisa N mensagens cifradas sem chave neste aparelho e aguardando nova chave (enquanto a troca não chega, publicar é recusado); group info mostra a visibilidade. Nenhum comando imprime chave: a chave de caixa do aparelho fica só em group-box.json (0600) no diretório de dados. O semeador guarda e serve só o texto cifrado. Quem é membro, quem posta e quando continuam visíveis. Detalhes em docs/protocol.md §10 ("Private groups") e checagens em docs/verification.md §62.

Demo automática

npm run demo

O mesmo programa é node apps/cli/scripts/demo.js. Ele sobe uma DHT em processo, em 127.0.0.1 (três nós), define VARANDA_BOOTSTRAP e VARANDA_DHT_HOST=127.0.0.1, e não fala com a DHT pública. Os dados ficam num diretório temporário, apagado no fim (salvo com --keep).

O que a demo mostra, nesta ordem:

  1. Duas associações de teste.
  2. Identidades de A (Ana) e de B.
  3. A associação certifica A e B; cada um grava o certificado no bloco 0.
  4. seed key, assoc certify-seeder e seed cert add.
  5. Ana define o perfil. B segue A ainda fora da rede.
  6. O semeador sobe (seed ready).
  7. Ana publica e faz sync --once com o semeador. O processo dela termina: Ana fica offline.
  8. O semeador recebe SIGTERM (código 0) e um processo novo abre o mesmo diretório, a partir do disco.
  9. B entra com sync --once e recebe a publicação só pelo semeador. O feed de B mostra o texto.
  10. B responde. Ana volta, segue B, sincroniza e lê a resposta no feed.
  11. C confia na primeira associação e tenta gravar um certificado emitido pela segunda. cert add sai com código 1 e untrusted-association no stderr. O sync de C não é admitido.
  12. Um segundo semeador que só tem seed key, sem certificado, não sobe: seed sai com código 1.

No sucesso o processo sai com código 0 e imprime DEMO OK. Na primeira falha imprime DEMO FALHOU: <passo> e sai com código 1.

--keep, ou VARANDA_DEMO_KEEP=1, conserva o diretório temporário:

npm run demo -- --keep

Operar o semeador

Para quem mantém um semeador ligado: comandos de operação, saúde e métricas, serviço supervisionado (Docker Compose ou systemd) e a política de registros. Os arquivos de implantação ficam em deploy/seeder/.

seed --no-dm desliga as mensagens diretas nesse semeador: ele não abre os canais varanda/dm/1 nem varanda/dm-stamp/1, não guarda o conjunto de envelopes e não emite selos, e o membro vê os dois canais como sem suporte. Ele também desliga a pista silenciosa de visitas (varanda/visit/1, um repositório à parte, sem acordar ninguém). Sem a opção, os três canais ficam ligados.

Com as mensagens diretas ligadas, o semeador também guarda a mídia cifrada das conversas: o canal anônimo varanda/blob/1 recebe pedaços selados com selos de mídia, assinados por um par de chaves à parte em <dados>/blob-postage.json (mesma rotação de 7 dias e mesmo limite de 14 dias de dm-postage.json; um arquivo com a mesma chave das mensagens é recusado e só os selos de mídia param). A contagem diária desses selos fica em <dados>/blob-stamps.json, separada de dm-stamps.json. A cópia do histórico para outro aparelho usa selos do tipo copy, contados por semana em <dados>/copy-stamps.json (8192 por diário e por semana), sem gastar a cota diária de mídia. Os pedaços ficam em <dados>/blobs/ por 14 dias, até --blob-bytes no total (padrão 4 GiB). seed --no-dm desliga também os selos de mídia, o canal e a rota /blob.

A mesma porta da entrada WebSocket serve GET ou HEAD /blob/<id>/<índice> (id em 64 hexadecimais minúsculos, índice decimal canônico): só um pedaço de uma mídia completa, exatamente como foi guardado, com Cache-Control: private, max-age=604800, sem autenticação e sem cookie. Qualquer outra coisa, inclusive um pedido com query string, é o mesmo 404 (não encontrado, sem cache), sem dizer se o id existe. Divide os limites de /media (16 respostas ao mesmo tempo e 64 pedidos por segundo, somando as duas rotas, senão 503 ocupado). Nada é registrado: nem id, nem índice, nem endereço.

Comandos de operação

seed status mostra a associação, a chave pública do semeador, o estado do certificado, quantos diários estão em admitted.json, se há uma lista de bloqueio ilegível guardada de lado e nenhuma verificada, caso em que a partida segura admissões (linha admissões: seguradas…, só quando é o caso; não prevê a primeira partida depois de um arquivo rasgado sem cópia) e se algum processo segura o diretório. Não pega o lock, não abre o store e não grava nada: funciona com o semeador ligado ou parado, e sai com 0.

associação: <64 hex>
chave do semeador: <64 hex>
certificado: válido
diários admitidos: 2
estado: em execução

Sem seeder-key.json a segunda linha é chave do semeador: ausente (use seed key). Sem certificado: certificado: ausente (use seed cert add); certificado que não confere: certificado: inválido (<motivo>). O estado é em execução ou parado. Num diretório que não é de semeador: erro: diretório não é de um semeador. Com --json: { "association", "publicKey", "certificate", "admitted", "running" }, com certificate igual a ok, missing ou o motivo.

seed list mostra os diários admitidos, um por linha, na ordem de admitted.json: <chave> <blocos> blocos <bytes> bytes, e embaixo de cada diário, recuados, os núcleos de fotos vinculados a ele:

<64 hex do diário> <blocos> blocos <bytes> bytes
  mídia <64 hex do núcleo> <blocos> blocos <bytes> bytes

O tamanho é o assinado, o mesmo que a cota confere. Sem diários: nenhum diário admitido. Com --json: { "admitted": [{ "key", "length", "byteLength", "media": [{ "key", "length", "byteLength" }] }] }. Uma chave listada sem cópia guardada aparece com 0 e 0.

seed drop <chave> apaga a cópia de um diário (e antes os núcleos de fotos dele) e só depois tira a chave de admitted.json, a mesma ordem do descarte na partida. A chave pode ser também a de um núcleo de fotos, que sai sozinho (a próxima leitura do diário o vincula de novo). Imprime diário removido do semeador: <chave>. Chave que não está no semeador: erro: diário não está no semeador (código 1). Sem chave: uso: informe a chave do diário; chave malformada: uso: chave inválida (código 2).

seed list e seed drop abrem o store e pegam o lock do diretório. Só funcionam com o semeador parado; com ele no ar saem com erro: diretório de dados em uso (código 1) e não mexem em nada. Pare o serviço, rode o comando e suba de novo.

seed drop não é bloqueio. No próximo sync da autora o semeador confere o bloco 0 e admite o diário outra vez. Para manter um diário fora, bloqueie a conta (veja "Bloquear uma conta").

Saúde e métricas

seed --health-port <porta> (ou VARANDA_HEALTH_PORT) abre um endpoint HTTP só de leitura em 127.0.0.1. Outro endereço só com --health-host (ou VARANDA_HEALTH_HOST); 0.0.0.0 expõe o endpoint para fora da máquina. Sem a porta, nada escuta. A porta 0 escolhe uma livre, e a primeira linha da saída diz qual: health http://127.0.0.1:<porta>. Porta ocupada termina com erro: porta em uso (código 1) antes de abrir o diretório.

  • GET /health devolve { "status", "uptimeSeconds", "admitted", "dropping", "activeDay", "activeWeek", "blocks", "bytes", "connections", "peers", "firewalled", "blocked", "blocklistSeq", "blocklistHeld", "mediaCores", "mediaBytes", "indexRecords", "indexSaturated", "topicPosts", "topicSaturated" }. Código 200 com status igual a ok; 503 com starting (antes de seed ready) ou closing (encerrando).
  • GET /metrics devolve as mesmas contagens no formato de texto do Prometheus: varanda_seeder_ready, varanda_seeder_admitted_diaries, varanda_seeder_dropping_diaries, varanda_seeder_active_diaries_day, varanda_seeder_active_diaries_week, varanda_seeder_blocks, varanda_seeder_bytes, varanda_seeder_connections, varanda_seeder_peers, varanda_seeder_firewalled, varanda_seeder_blocked, varanda_seeder_blocklist_seq, varanda_seeder_blocklist_held, varanda_seeder_media_cores, varanda_seeder_media_bytes, varanda_seeder_index_records, varanda_seeder_index_saturated, varanda_seeder_topic_posts, varanda_seeder_topic_saturated e varanda_seeder_uptime_seconds.
curl -s http://127.0.0.1:8788/health
{"status":"ok","uptimeSeconds":42,"admitted":2,"dropping":0,"activeDay":1,"activeWeek":2,"blocks":6,"bytes":1418,"connections":3,"peers":3,"firewalled":false}

admitted são os diários servidos e dropping os que estão sendo apagados. activeDay são os diários servidos cujo tamanho assinado cresceu no dia de Brasília (UTC−3) de hoje, e activeWeek os que cresceram nos últimos 7 dias de Brasília (UTC−3), hoje incluído. As duas são aproximadas, ficam só na memória do semeador e zeram quando ele reinicia; um diário admitido pela primeira vez nesta execução conta, e as contagens nunca dizem quais diários. blocks e bytes somam os diários servidos; connections são as conexões abertas e peers as que já abriram o canal de admissão. firewalled: true quer dizer que a DHT se vê atrás de firewall ou NAT: os membros só chegam ao semeador por hole punching. mediaCores são os núcleos de fotos vinculados a diários admitidos e mediaBytes o tamanho assinado deles. indexRecords são os registros no índice de engajamento (em memória) e indexSaturated: true quer dizer que ele chegou ao limite e há diários pausados (as respostas de /index dizem complete: false). topicPosts são as publicações no índice de busca por assunto (em memória) e topicSaturated: true quer dizer que ele atingiu um limite e há diários pausados (as respostas de /index/topic dizem complete: false); só contagens, nunca as palavras pesquisadas.

As fotos saem pela mesma porta da entrada WebSocket (--ws-port), em GET ou HEAD /media/<diário>/<núcleo>/<início>/<blocos>, que o Caddy da versão web encaminha. Só um núcleo vinculado a um diário admitido e não bloqueado, com todos os blocos já guardados, é servido; qualquer outra coisa é o mesmo 404 (não encontrado), sem dizer o motivo. No máximo 16 respostas ao mesmo tempo e 64 pedidos por segundo no total (senão 503 ocupado), 256 blocos por pedido e 120 s por resposta. Nada é registrado. Detalhes em docs/protocol.md seção 7.

O endpoint só tem contagens. Nenhuma chave, certificado, endereço ou conteúdo, e nenhuma requisição é registrada. Aceita só GET e HEAD (senão 405) em /health e /metrics (senão 404), sem cabeçalhos CORS.

Entrada WebSocket

seed --ws-port <porta> (ou VARANDA_WS_PORT) abre uma entrada WebSocket em ws://127.0.0.1:<porta>/seeder, para um membro que roda no navegador. É um experimento da fase 0. Outro endereço só com --ws-host (ou VARANDA_WS_HOST); o padrão é 127.0.0.1. Sem a porta, nada escuta. A porta 0 escolhe uma livre, e a saída diz qual: ws ws://127.0.0.1:<porta>/seeder. Porta ocupada termina com erro: porta em uso (código 1) antes de abrir o diretório.

Os bytes do WebSocket são um fluxo Noise com a chave do semeador, o mesmo que o membro vê pela DHT. Um proxy TLS pode repassá-los, mas não pode terminar o Noise. Essas conexões entram em connections do /health. Só o caminho /seeder aceita o upgrade; qualquer outro devolve 404, e um GET /seeder sem upgrade devolve 426. O cabeçalho Host precisa nomear a própria entrada (127.0.0.1:<porta>, localhost:<porta> ou [::1]:<porta> no loopback); outro devolve 421, o que barra o DNS rebinding. Clientes sem Origin (a CLI, apps nativos) entram normalmente; um navegador só entra se a origem estiver na lista permitida, que por padrão aceita apenas páginas http em loopback (qualquer outra devolve 403). --ws-origin <origem> (repetível, ou VARANDA_WS_ORIGIN) troca esse padrão pelas origens dadas, como a do PWA publicado (seção "Pôr a versão web no ar"). As conexões externas têm um limite próprio, independente do limite de conexões do enxame, definido por VARANDA_MAX_EXTERNAL (padrão 32), para que abas abertas não deixem os membros do enxame sem vaga.

Docker Compose

deploy/seeder/compose.yaml sobe a imagem de deploy/seeder/Dockerfile: Node 24, só as dependências de produção da CLI, o LICENSE do repositório em /app/LICENSE, usuário node, sistema de arquivos só de leitura e os dados no volume seeder-data (em /data). O serviço usa a rede do host, reinicia sozinho (unless-stopped), recebe SIGTERM com 30 s para fechar e deixa o endpoint de saúde em 127.0.0.1:8788, onde o healthcheck da imagem o consulta. É para um servidor Linux: no Docker Desktop a rede do host não funciona do mesmo jeito.

Configuração, uma vez, a partir da raiz do repositório (ASSOC é a chave pública da associação):

docker compose -f deploy/seeder/compose.yaml build
docker compose -f deploy/seeder/compose.yaml run --rm seeder seed key --association "$ASSOC"

A associação certifica a chave impressa, na máquina dela (assoc certify-seeder --seeder <chave> --out seeder-cert.json). Com o arquivo no diretório atual:

docker compose -f deploy/seeder/compose.yaml run --rm -v "$PWD/seeder-cert.json:/cert/seeder-cert.json:ro" seeder seed cert add --cert-file /cert/seeder-cert.json

Daí em diante, um comando sobe o semeador e outro mostra a saúde:

docker compose -f deploy/seeder/compose.yaml up -d
curl -s http://127.0.0.1:8788/health

docker compose -f deploy/seeder/compose.yaml ps mostra (healthy) depois de seed ready. Registros: docker compose -f deploy/seeder/compose.yaml logs -f seeder. Estado sem parar: docker compose -f deploy/seeder/compose.yaml exec seeder node apps/cli/bin/varanda.js seed status. Para seed list ou seed drop, pare antes (stop), rode com run --rm seeder seed list e suba de novo (start). Não use run com o serviço no ar: cada contêiner tem os próprios pids, e o lock do diretório não enxerga o processo do outro. O lock do RocksDB em store/ ainda barra o segundo processo (erro: File descriptor could not be locked, nada é apagado), mas o run remove o .varanda-lock do semeador no ar, e seed status passa a dizer parado até ele reiniciar.

Pôr a versão web no ar

A versão web (o PWA: o app com o nó no navegador, a identidade derivada de uma passkey) fica no mesmo servidor do semeador. deploy/seeder/compose.web.yaml complementa o compose.yaml: liga a entrada WebSocket do semeador só em 127.0.0.1:8789, aceitando apenas a origem https://<domínio>, e sobe um Caddy (deploy/seeder/Caddyfile) que pede o certificado TLS sozinho, serve o app publicado em deploy/seeder/www e repassa wss://<domínio>/seeder ao semeador. O Caddy só termina o TLS: o Noise vai do navegador ao semeador, que o membro verifica pelo certificado do semeador.

Nota: a prévia dos links de convite nos mensageiros muda deploy/seeder/Caddyfile, então o Caddy precisa ser reimplantado (e o serviço de conta, que passa a responder /account/og/convite/<código>). Detalhes em docs/verification.md, seção 128.

Antes: o semeador configurado como na seção anterior; um registro DNS (A e/ou AAAA) do domínio apontando para o servidor; as portas 80 e 443 abertas (o semeador usa a DHT por UDP, como antes). Da raiz do repositório:

cp deploy/seeder/.env.example deploy/seeder/.env    # e ponha o domínio em VARANDA_DOMAIN e a associação em VARANDA_ASSOCIATION
bash deploy/seeder/build-web.sh                     # gera o app num contêiner Node e o publica em deploy/seeder/www
docker compose -f deploy/seeder/compose.yaml -f deploy/seeder/compose.web.yaml up -d --build

VARANDA_ASSOCIATION é a chave pública da associação (64 dígitos hexadecimais, a mesma em que o semeador confia: seed status a mostra), e precisa estar em deploy/seeder/.env antes do up: o compose recusa subir sem ela. O Caddy a serve em https://<domínio>/varanda.json ({"v":1,"association":"..."}, sem endereço: a página usa wss://<domínio>/seeder), e é daí que o app se configura sozinho.

Depois abra https://<domínio>/ (confira também curl https://<domínio>/varanda.json). O build-web.sh e o deploy também publicam https://<domínio>/version.json ({"v":1,"commit":"<40 hex>"} mais LF), um arquivo comum de www: no-cache como o resto, 404 de verdade quando falta, e o service worker nunca o intercepta. O commit sai do checkout, nunca do contêiner de build; num checkout sem git o arquivo sai de www e o app mostra desconhecido. Ajustes mostra esse commit ao lado do commit do próprio app, então um app instalado atrás do servidor fica visível; o que falta aparece como desconhecido. O carimbo do app é EXPO_PUBLIC_VARANDA_COMMIT, embutido junto com EXPO_PUBLIC_VARANDA_BUILD_DATE por scripts/resolve-build-info.js. Os membros não preenchem mais a tela Conectar: a página só mostra "Entrar". Cada pessoa cria uma passkey (num gerenciador de senhas que sincroniza entre aparelhos) e, depois da cerimônia do emissor (seção seguinte), vincula a conta ao celular brasileiro verificado na etapa Identidade e recebe o certificado de membro sozinha, sem colar nada; antes dessa cerimônia o vínculo responde "serviço indisponível". No app com configuração manual (tela Conectar, Avançado), na CLI e no varanda-serve o certificado ainda vem da associação (assoc certify --member <chave>) e é colado (ou gravado com cert add). A cada atualização do código, sem a implantação automática da próxima seção: git pull, bash deploy/seeder/build-web.sh e o mesmo up -d --build.

Depois de uma visita com rede que guarde o app no aparelho, o PWA também abre sem rede, instalado (pela sugestão do próprio app ou pelo menu do navegador) ou numa aba. Entrar funciona se o autenticador da passkey funcionar sem rede; A Rua, Seguindo e Diário mostram o que já está no aparelho. Publicações e respostas ficam na fila de saída, no Diário, e saem uma a uma quando a conexão volta, com a página aberta, a identidade desbloqueada e nenhuma sincronização em andamento. Só sai sozinho o que foi escrito com a página aberta; o que ficou de uma visita anterior espera a pessoa tocar em "enviar" no Diário, para que uma publicação plantada no aparelho enquanto a identidade estava bloqueada não saia com a chave do membro. A data é a de quando a publicação entra no diário, não a de quando foi escrita; envios incertos pedem uma decisão da pessoa. Apagar os dados do site perde a fila ainda não enviada. Detalhes e limites em docs/app.md.

A exportação gera sw.js com os arquivos desta versão conferidos por SHA-256 e a marca varanda-release no index.html. O worker só é registrado na página hospedada em HTTPS com o nó no navegador, nunca em localhost nem com varanda-serve; ele não guarda respostas durante o uso e confere de novo o SHA-256 de cada arquivo guardado a cada leitura, antes de entregá-lo. Navegações buscam a rede primeiro e usam a cópia guardada desta versão se a rede falhar ou responder 404/5xx; arquivos com hash usam primeiro essa cópia. A exportação também copia varanda-node.js para varanda-node-<versão>.js, o nome que a página carrega, e só essa cópia é guardada: uma página, inclusive a cópia guardada servida enquanto uma implantação troca os arquivos, só roda o nó da própria versão, e varanda-node.js fica só na rede (as sondas de implantação conferem os dois nomes). HTML no endereço de um script ou de outro recurso é recusado, e um index.html sem CSP rígida ou sem nosniff também. No Caddy, todos os arquivos de /srv/web usam Cache-Control: no-cache, revalidado por ETag, para que uma cópia incompleta durante a implantação se corrija na carga seguinte. Um caminho com extensão que não existe recebe 404, e todo 404 recebe no-store e os mesmos cabeçalhos de segurança (CSP, nosniff) das outras respostas; só caminhos sem extensão recebem index.html. /varanda.json continua com no-store.

Para o app instalado (iOS e Android) entrar com a mesma passkey do site, o domínio publica /.well-known/assetlinks.json e /.well-known/apple-app-site-association, gerados por deploy/seeder/well-known.sh a partir de duas variáveis opcionais de deploy/seeder/.env:

  • VARANDA_ANDROID_CERT_SHA256: a impressão digital SHA-256 do certificado de assinatura da versão de lançamento do app Android, em 64 hexadecimais maiúsculos separados por dois-pontos. Vem de eas credentials -p android (o certificado de assinatura do build de lançamento), nunca da chave de depuração. O serviço account também a recebe (compose.web.yaml), para aceitar a passkey do app Android em Excluir conta; um valor fora da forma faz o serviço recusar subir.
  • VARANDA_IOS_APP_ID: o identificador do app no iOS, no formato TEAMID.app.varanda (o Team ID da conta Apple Developer mais o identificador do pacote).

O assetlinks.json declara get_login_creds (a passkey) e handle_all_urls. O app declara como seus (App Links, autoVerify) só os links /c/<chave> e /g/<chave> de bora.varanda.app; os outros links do domínio continuam no navegador, e outra instalação não ganha App Links. O build de depuração (app.varanda.debug) não entra no assetlinks.json. Vazio desliga a entrada nativa naquela plataforma (a implantação avisa e segue); um valor fora da forma recusa a implantação. deploy/seeder/well-known.sh é lido por deploy.sh e build-web.sh como root: ele precisa ser de root e sem escrita para grupo ou outros, como o deploy.sh. Depois de mudar o deploy/seeder/Caddyfile, rode caddy validate --config deploy/seeder/Caddyfile --adapter caddyfile antes de subir. O fluxo de vínculo da conta pelo app está em "Vínculo pelo app nativo", mais abaixo.

Limites desta fase: a chave do membro é derivada da passkey (extensão PRF) e nunca é gravada: ela só existe na memória da página enquanto a identidade está desbloqueada, perder a passkey perde a identidade e um navegador sem PRF não entra (ver docs/verification.md seção 10); a passkey vale para o endereço exato da página; a página continua tão confiável quanto o código que o servidor entrega. Com rede, uma nova carga busca código fresco e instala a nova versão do worker; ela assume depois que todas as janelas do app são fechadas, sem forçar a troca numa janela aberta. Sem rede, o aparelho roda a última versão que recebeu e guardou por inteiro. A entrada WebSocket ainda não tem os limites para a internet aberta previstos no PR de endurecimento. Use com um grupo pequeno de pessoas de confiança. O Caddy não grava registro de acesso; os erros que ele registra podem incluir o endereço do cliente (mesma rotação do semeador).

Vínculo de conta Google e @nome (serviço account)

O compose.web.yaml também sobe o serviço account, que liga a passkey de um membro a um celular brasileiro verificado e dá a ele um @nome e um certificado de membro automático. O app instalado usa o mesmo serviço (veja "Vínculo pelo app nativo"). O Caddy repassa /account/* a ele. Dois valores continuam obrigatórios em deploy/seeder/.env (veja .env.example), agora só para o painel de moderação:

  • VARANDA_GOOGLE_CLIENT_ID e VARANDA_GOOGLE_CLIENT_SECRET: um cliente OAuth do Google Cloud. No console (APIs e serviços, Credenciais), crie um "ID do cliente OAuth" do tipo "Aplicativo da Web"; em "URIs de redirecionamento autorizados" ponha https://<domínio>/account/mod/callback; na tela de consentimento use os escopos openid e email. Copie o ID e o segredo para o .env. O segredo nunca vai para o repositório nem para registros.

Depois de confirmar o celular (e a idade, quando a instalação a exige; veja "Verificação de celular"), o app chama POST /account/start sem assinatura e recebe um nonce. Assina com account.sign, fase finish, usando sub: "telefone:<chave>" (<chave> é a chave pública do membro), e envia a assinatura a POST /account/finish. O vínculo guarda esse sub e e-mail vazio; o número fica lacrado no phone.json. Os membros anteriores mantêm o sub Google e o e-mail no diretório. Sem a configuração de celular, não há cadastro novo e o serviço registra uma linha com evento cadastro: cadastro de novas contas desligado: verificação de celular não configurada.

Um @nome novo (no vínculo e na troca) com um termo da lista curta da conferência de palavras do app (BLOCKED_TERMS de @varanda/rpc) recebe nome-invalido, e o log da recusa traz só esse motivo. Um @nome que a conta já tem não é conferido de novo.

O vínculo Google de membros foi retirado: POST /account/authorize responde 410 versao-antiga, mesmo sem configuração; /account/callback não troca código nem faz pedido externo e redireciona para /?conta=erro. A leitura de /account/pending e a volta /account/app/conta respondem 404 expirado. A conclusão também responde expirado se a verificação de celular estiver desligada, se o pendente já passou da fase reserve ou se guarda um sub Google. O login Google do painel continua em /account/mod/*.

Implante a retirada (feat/retire-google-member-link) só depois de a versão do app com feat/phone-only-signup-app estar nas lojas e de as versões antigas terem tido um ciclo de revisão das lojas para atualizar. Até lá, mantenha o servidor com feat/phone-only-signup-server, que atende os dois fluxos.

O serviço sobe sem emissor: até a cerimônia abaixo, /account/health responde {"status":"ok"} e o início e a conclusão do vínculo respondem 503 indisponivel. As rotas retiradas mantêm as respostas acima. A cerimônia roda DEPOIS da primeira implantação com o serviço (a imagem varanda-seeder:local só passa a ter o comando account depois do up -d --build). Da raiz do repositório no servidor, com o serviço account parado se já estiver rodando (docker compose -f deploy/seeder/compose.yaml -f deploy/seeder/compose.web.yaml stop account):

  1. Gere a chave do emissor dentro do volume do serviço; o comando imprime só a chave pública:

    docker compose -f deploy/seeder/compose.yaml -f deploy/seeder/compose.web.yaml run --rm account account key
  2. Na máquina do operador (onde está a associação), certifique essa chave pública:

    node bin/varanda.js assoc certify-issuer --data <assocDir> --issuer <hex> --out issuer-cert.json
  3. Copie só esse arquivo público (issuer-cert.json) para o servidor e grave-o no serviço:

    docker compose -f deploy/seeder/compose.yaml -f deploy/seeder/compose.web.yaml run --rm -v $PWD/issuer-cert.json:/cert/issuer-cert.json:ro account account cert add --cert-file /cert/issuer-cert.json
  4. Reinicie o serviço: docker compose -f deploy/seeder/compose.yaml -f deploy/seeder/compose.web.yaml restart account. Depois disso account status deixa de dizer emissor não certificado.

O association.json nunca sai da máquina do operador, e o segredo do emissor nunca sai do volume do serviço account. O account cert add recusa um certificado de outra associação ou de outra chave.

Com VARANDA_MAX_MEMBERS definido, quando o número de contas vinculadas chega ao teto, um vínculo que criaria um membro novo recebe "lista de espera" (HTTP 503) e o app mostra uma tela calma com essa resposta. O diretório não grava o vínculo nem o @nome escolhido, e a linha pendente é apagada se a recusa vier na conclusão. Um celular confirmado antes da recusa segue a retenção do phone.json: é apagado em 7 dias se o cadastro nunca terminar. Quem já é membro segue normalmente: renomear, ver o status e denunciar continuam funcionando. Uma chave nova conta como membro novo e também espera. Baixar o teto abaixo do número atual não remove ninguém. O semeador tem o próprio limite de 4096 diários, que continua valendo: mantenha VARANDA_MAX_MEMBERS igual ou abaixo dele.

O app hospedado (web, e o app instalado ligado a uma instalação hospedada) avisa antes de a pessoa criar a passkey: na tela Entrar ele pergunta GET /account/admission, público, sem autenticação e com o mesmo limite de consultas de GET /account/invites/policy, que responde exatamente { "open": true } ou { "open": false }. false só enquanto VARANDA_MAX_MEMBERS está batido, e a resposta nunca traz contagem. Com open: false o app mostra a frase "A Varanda está cheia por enquanto..." com o botão "tentar de novo" e não oferece "Criar minha conta", "criar mesmo assim" nem "criar com o celular"; "Entrar", "entrar com o celular", outra passkey, o código de recuperação, "Concluir e entrar" e "Criar passkey nova" depois de um código de recuperação continuam. Se a leitura falha (rede, serviço antigo que responde 404, qualquer outro corpo), o app não bloqueia, e o serviço ainda recusa com "lista de espera" em POST /account/start, em POST /account/finish e em POST /account/age/session se a vaga acabar no meio da entrada. A leitura não reserva vaga, um convite não abre vaga, e required: false na política de convites continua não significando que há vaga. A resposta vale por instalação: trocar de instalação pergunta de novo. Uma configuração digitada à mão na página hospedada, a configuração manual e o varanda-serve não perguntam e seguem como antes.

Convites

Com VARANDA_INVITES_PER_WEEK definido, um vínculo que criaria um membro novo só termina com um convite válido. Quem já é membro não precisa de convite: renomear, ver o status e denunciar continuam como antes. Sem a variável (ausente ou vazia), o cadastro não exige convite: GET /account/invites/policy ainda responde { "required": false } e as rotas POST de convite não existem.

  • O link. https://<origem>/convite/<código>. O código tem 32 bytes aleatórios em base64url, é mostrado uma única vez ao membro que o cria e o serviço guarda só o SHA-256 dele, e só enquanto o convite não foi usado. Cada link vale para uma pessoa só e por 7 dias depois de criado.
  • Quanto cada membro pode convidar. Cada membro vinculado ganha N convites por semana civil de Brasília (UTC-3, sem horário de verão), de segunda 00:00 até a segunda seguinte. Um convite criado conta na semana em que foi criado, mesmo sem uso; o que sobra não acumula; não há revogação nem devolução. Todos seguem N, o operador também, e não existe comando de emissão. Baixar N não apaga os links já criados na semana. A semana segue o relógio do servidor.
  • A primeira pessoa. Numa rede vazia ninguém pode emitir convite. A primeira pessoa precisa vincular com a variável vazia e só depois o operador a define. Não há exceção.
  • varanda assoc certify fica fora do portão. Um membro só certificado não é vinculado, logo não emite convite.
  • O que o serviço guarda. No invites.json (modo 0600, ao lado do directory.json): um identificador aleatório de cada convite, a chave de quem o criou, a data de criação, se foi usado e, enquanto não foi usado, o hash do código. Nunca e-mail, nome, sub ou chave de quem entrou. O uso único é decidido pelo diretório: o registro do vínculo de quem entrou guarda o hash do convite usado, e um segundo vínculo com o mesmo convite é recusado na hora, sem depender do invites.json. Por isso o invites.json apaga o hash quando o convite é usado e não guarda quando. Quem convidou quem pode ser reconstruído a partir de uma cópia antiga do invites.json (de antes do uso) e, de forma aproximada, pelas datas.
  • O caminho. No app, o membro vinculado abre Ajustes › Convidar pessoas, vê quantos convites pode criar por semana e cria o link; depois de criar, vê quantos restam. Quem recebe abre o link, e o app guarda o código só na aba (sessionStorage, chave varanda-signup-invite) e o envia ao serviço no início do vínculo. O serviço confere o convite no início e na conclusão. Uma recusa na conclusão deixa o convite utilizável. Uma recusa na conclusão por @nome em uso ou conta já vinculada também apaga a linha pendente e libera o convite na hora, para a pessoa recomeçar.
  • Rotas. GET /account/invites/policy ({ required, perWeek }), POST /account/invites/start e POST /account/invites/finish (o membro assina com invite.sign, ver docs/rpc.md 5.30; a resposta traz o código uma vez e quantos convites o membro já usou e ainda tem na semana). GET /account/status não traz contagens de convite: a chave de um membro é pública. Recusas: convite-obrigatorio (403), convite-invalido (404), limite-convites (429), convite-aguardando (429, só com os convites de surpresa), e indisponivel se o invites.json não puder ser lido.
  • varanda account status. Mostra só contagens: convites: <total> (<usados> usados), nunca um código ou uma chave.
  • Convites de surpresa. Com VARANDA_INVITE_DROPS=1 (e VARANDA_INVITES_PER_WEEK definido), cada membro vinculado recebe N momentos por semana de Brasília, em vez de N convites abertos na segunda. Cada momento é sorteado entre 09:00 e 20:59 (horário de Brasília), só entre os minutos ainda futuros depois do vínculo do membro e da ativação do recurso, e é diferente para cada membro. O sorteio sai de invite-drops-key.json (modo 0600, escrito uma vez, com o segredo e a data de ativação, no volume account-data); um arquivo inválido deixa as concessões indisponíveis em vez de liberar a semana inteira. O invite-drops.json (modo 0600) guarda só quais momentos de cada membro já foram avisados, sem horário, e é podado no fim da semana. Um convite não usado some na segunda 00:00; um código já emitido vale 7 dias como sempre. O aviso push só sai dentro da janela, e nos 2 minutos antes das 21:00 nenhum momento é reservado (ele fica para a próxima janela da mesma semana), menos no domingo, que não tem outra janela na semana: se o serviço estava parado no minuto sorteado, o aviso é recuperado uma vez na próxima janela, desde que a semana seja a mesma. Mudar N vale na hora, como sem o recurso. Uma duplicata do aviso só é possível na janela de troca do lock (invites-store.js, a mesma que o invites.json já tem). Quem tem a instalação hospedada vê, em Ajustes › Convidar pessoas, quantos convites já chegaram, sem dia nem hora. Até o momento, criar o link responde convite-aguardando (429). A rota POST /account/invites/summary (o membro assina com invite.sign na ação summary, ver docs/rpc.md 5.30) responde { mode, perWeek, opened, used, remaining, resetsAt }, com mode semanal ou sorteio (também sem o recurso, com semanal), no máximo 30 pedidos por 10 minutos por membro e sem verificação de idade, porque não cria nada. A política pública (GET /account/invites/policy) não muda. Ver docs/verification.md, seção 97.

Limites conhecidos (detalhes em docs/verification.md, seção 37): uma queda ou perda do lock do serviço no meio da criação pode gastar o convite da semana sem entregar o link; um erro passageiro de leitura do invites.json deixa os convites indisponíveis até reiniciar o serviço (como o terms.json); o invites.json e o diretório são arquivos separados, então uma gravação atrasada de um processo que perdeu o lock pode desfazer a contagem da semana, sem afetar o uso único; em navegação privada que recusa o armazenamento da aba, o código fica só na memória da página e não sobrevive a recarregá-la, e a pessoa abre o link de novo se o vínculo não terminar. Um pendente antigo que já guarda um sub (deixado pelo callback Google aposentado) só pode ser substituído no início por quem apresenta seu cookie na web ou V no app; sem essa prova, o convite fica reservado até o pendente vencer (10 minutos).

O diretório de contas fica no volume account-data em três arquivos: directory.json (o retrato, com seq), directory.journal.<id> (o diário de mudanças, uma linha por vínculo, troca de e-mail ou troca de @nome; <id> é o identificador que o retrato guarda) e directory.hwm (a marca d'água: o maior seq já confirmado, com o número de vínculos e de @nomes naquele ponto). Cada mudança grava uma linha no diário e a confirma com fsync, sem reescrever o diretório inteiro. Ao chegar a 256 linhas, ao passar de 1 MiB e a cada abertura do serviço (mesmo com o diário vazio), o serviço compacta: cria um diário novo (com identificador novo), reescreve o retrato apontando para ele e só então apaga o diário anterior; um diário nunca é truncado nem reescrito. Um corte de energia no meio de uma linha deixa uma linha incompleta, que o serviço ignora e a próxima abertura para escrita descarta; um corte no meio de uma compactação deixa um diário órfão (que nenhum retrato nomeia), que uma abertura para escrita remove depois de 40 segundos sem gravação nele (antes disso ele pode ser de um serviço que ainda não percebeu que perdeu o lock) e depois de conferir de novo que o retrato não o nomeia. Os três arquivos têm modo 0600.

O retrato e o diário andam juntos: o retrato na versão 2 guarda o identificador do seu diário, e a primeira linha do diário traz esse identificador. Se o diário sumir, ficar vazio ou trouxer outro identificador, ou se um diário órfão trouxer uma mudança além do retrato, o serviço (e account status, account export e account reports) recusa o diretório com diretório de contas inválido, em vez de esquecer vínculos e entregar de novo um @nome. Enquanto roda, o serviço confere antes e depois de cada gravação que o diário é o mesmo arquivo, com o tamanho esperado, e que o directory.json é o mesmo arquivo que ele leu ou gravou por último; se alguém mexeu neles, ou se o serviço perdeu o lock e outro serviço assumiu o diretório (toda abertura do novo serviço troca o directory.json e apaga o diário antigo, mesmo vazio), o serviço para de gravar e responde "indisponível" até ser reiniciado; uma linha gravada bem na troca não é confirmada a quem pediu. Um diário órfão com uma mudança além do retrato só abre quando o diário nomeado traz a mesma linha (uma queda bem no fim de uma compactação). Uma falha do disco ao confirmar uma linha (fsync) tem o mesmo efeito. Nunca gire (rotacione), apague ou esvazie um directory.journal.*: ele não é um log. O backup do volume leva os três arquivos juntos, com o serviço parado.

Restaurar um backup é um evento de segurança. O backup copia os três arquivos juntos, com o serviço parado; ao restaurar, restaure só o directory.json e o directory.journal.* que ele nomeia, sempre da cópia MAIS RECENTE, e MANTENHA o directory.hwm que já está no volume (restaure o directory.hwm do backup apenas se o volume o perdeu): sobrescrever a marca atual pela do backup a baixaria e a recusa de cópia restaurada nunca dispararia. uma cópia mais antiga faz o diretório esquecer vínculos e @nomes criados depois dela, e esses nomes poderiam ser entregues de novo a outra pessoa. Por isso o directory.hwm guarda o maior seq confirmado e o número de vínculos e de @nomes naquele ponto (atualizado a cada compactação e na parada limpa, nunca para trás) fora do par retrato+diário: se o par restaurado termina abaixo dessa marca, o serviço recusa abrir com diretório de contas restaurado de uma cópia antiga; confira o backup (e registra store restaurado), e account status, account export e account reports ainda leem, mas avisam. Um directory.json com seq é julgado pelo seq; um sem seq (gravado por uma versão anterior, ver abaixo) é julgado só pelas contagens: recusado quando tem menos vínculos ou menos @nomes que a marca. Confira primeiro se não há um backup mais recente. Se a restauração de uma cópia antiga for mesmo intencional, o operador a reconhece apagando o directory.hwm depois de confirmar que nenhum vínculo nem @nome foi criado desde aquela cópia; o próximo serviço grava uma marca nova a partir dela. Mudanças feitas depois da última compactação ou parada limpa e perdidas numa queda não entram na marca.

Criar a primeira página é uma migração de mão única do diretório de contas: depois dela, uma versão anterior recusa o diretório, e voltar a ela só é possível com a cópia do volume account-data feita antes da primeira página. Antes de voltar a uma versão anterior a esta, pare o serviço com a parada limpa: docker compose -f deploy/seeder/compose.yaml -f deploy/seeder/compose.web.yaml stop account. Confira que o directory.json traz "v":1 e que não há nenhum arquivo directory.journal.*; só então suba a versão anterior (ela ignora o directory.hwm). Se a parada registrar close falhou (e o serviço sair com código 1), ou se o serviço foi morto à força (ou saiu com lock perdido), o directory.json fica na versão 2 (toda abertura desta versão o grava assim), que a versão anterior recusa com diretório de contas inválido. Nesse caso, suba esta versão, deixe-a abrir o diretório, pare-a com a parada limpa e só então volte. Para voltar a esta versão depois, não é preciso mexer no directory.hwm: a versão anterior grava o directory.json sem seq, e esta versão o compara pelas contagens com a marca, abre se nenhum vínculo nem @nome se perdeu e segue a numeração a partir da marca. Só apague o directory.hwm se a volta for recusada com restaurado de uma cópia antiga e a perda de vínculos ou @nomes for mesmo intencional.

Os aceites dos Termos de Uso e da Política de Privacidade ficam num arquivo à parte no mesmo volume, terms.json (modo 0600): para cada chave de membro, a versão aceita, a data (do relógio do serviço), o nonce e a assinatura que provaram o aceite; nunca o e-mail. Só um membro já vinculado registra aceite (POST /account/terms/start e /account/terms/finish, com uma prova da chave do diário) e lê de volta se o serviço guarda a versão atual (POST /account/terms/held/start e /account/terms/held/finish, com a prova summary da chave do diário; uma leitura por membro, no máximo 30 a cada 10 minutos). GET /account/status não traz a versão aceita. Inclua terms.json no backup do volume account-data, junto do diretório de contas. Restaurar uma cópia mais antiga perde os aceites feitos depois dela, e os aparelhos que já sincronizaram o aceite não o reenviam. account export traz em cada linha o campo terms, a lista [{ "version", "acceptedAt" }] dos aceites daquele membro ([] sem aceite; nunca o nonce nem a assinatura), e sai com terms.json inválido (código 1) se o arquivo estiver corrompido; account status mostra aceites dos termos: <n> ou aceites dos termos: indisponível (terms.json inválido). Com o arquivo inválido o serviço continua no ar, registra terms indisponivel e responde "indisponível" (HTTP 503) só nessas rotas. Uma versão anterior a esta ignora o terms.json e responde 404 nas duas rotas: voltar a ela não perde os aceites gravados, que reaparecem quando esta versão volta.

As passkeys extras e o código de recuperação de cada membro (Ajustes › Passkeys e recuperação) ficam noutro arquivo à parte no mesmo volume, recovery.json (modo 0600): por identificador derivado, a chave do membro, o tipo (passkey ou code), a data e a raiz embrulhada, um texto cifrado que o serviço não consegue abrir. As rotas são POST /account/recovery/start, /put, /remove, /list (com uma prova da chave do diário, só para membro vinculado) e /fetch (o identificador vai só no corpo do POST). São até 4 passkeys extras e 1 código por membro (limite-recuperacao, HTTP 409). O /start não guarda nada (o nonce leva a validade e uma assinatura do próprio serviço) e não tem cota por membro, então ninguém bloqueia outro membro pedindo nonces em nome dele; o nonce só é gasto depois de uma prova válida. Remover ou trocar uma entrada só impede novas entradas com ela: quem já entrou com aquela passkey ou aquele código continua com acesso, porque a chave da conta não pode ser trocada, e o único caminho seguro depois de um vazamento é criar uma conta nova. Inclua recovery.json no backup do volume account-data; se ele se perder, cada membro entra com a passkey original ou num aparelho ainda conectado e cadastra as entradas de novo. Com o arquivo corrompido o serviço continua no ar, registra recovery indisponivel, nunca regrava o arquivo e responde "indisponível" (HTTP 503) só nas rotas /account/recovery/*. O arquivo não entra em account export nem em account status, e os registros do serviço nunca trazem o identificador, o texto cifrado nem a chave. Detalhes em docs/protocol.md ("Files and replicas").

Se houver um directory.journal.* antes de voltar (um diário órfão), suba esta versão de novo, espere mais de 40 segundos para que a limpeza de órfãos o remova, pare-a com a parada limpa e confira de novo. O deploy.sh desfaz o deploy sozinho recriando o contêiner account com um fechamento por SIGTERM, que deixa a versão 1 só se esse fechamento der certo; se o contêiner account estava parado ou reiniciando naquele momento, o diretório continua na versão 2 e a imagem anterior o recusa até que os passos manuais acima sejam seguidos.

Vínculo pelo app nativo

O app nativo faz o mesmo vínculo por celular e usa o segredo V no lugar do cookie __Host-varanda-link da web. Não há volta do Google nem código de resgate R:

  • Cabeçalho. Os pedidos do app trazem x-varanda-client: app. Um POST sem cabeçalho Origin só é aceito com esse cabeçalho e com corpo JSON (uma página de outro site não envia nenhum dos dois sem uma consulta prévia de CORS, que o serviço nunca responde). Um Origin presente continua tendo de ser exatamente a origem pública; null é recusado.
  • Segredo V. O app sorteia 32 bytes (V) e os guarda só na memória. No início envia apenas appProof, o SHA-256 de V em base64url (43 caracteres), e não recebe cookie. A conclusão envia V no cabeçalho x-varanda-link, junto da assinatura no corpo, sem x-varanda-redeem. O serviço guarda só o appProof e compara em tempo constante. Recomeçar com V abandona a linha anterior, que não conclui mais.
  • Idade. Com o cabeçalho do app, a sessão do Didit volta para https://<domínio>/account/age/app-return, que ignora qualquer parâmetro e redireciona para varanda://idade?volta=1; o app pergunta o resultado com a assinatura, como a web. O domínio permitido no Didit continua o mesmo. Uma sessão aberta pela web só é reaproveitada pela web, e a do app só pelo app: quem usa os dois na mesma hora abre duas sessões pagas.

Os registros nunca trazem V, appProof, sub, e-mail, número de celular nem código de SMS.

Verificação de idade (Didit, serviço account)

Na web hospedada, todo membro, novo ou já vinculado, confirma a idade antes de usar o app. A idade mínima é 16 (decisão do produto com base no ECA Digital, sujeita a parecer jurídico). A pessoa é enviada à página do Didit, por navegação de página inteira, e volta para https://<domínio>/?idade=volta. O serviço account pergunta a decisão ao Didit por conta própria e nunca confia na URL de volta.

Configuração do operador:

  • Crie a aplicação no Didit e um workflow com estimativa de idade por rosto e documento de reserva.
  • Defina o domínio permitido como a origem pública. O callback é https://<domínio>/?idade=volta.
  • A chave da API precisa dos privilégios read:sessions e delete:sessions e não pode ser restrita a um workflow ou a um status: o Didit responde 404 a uma chave restrita, e o serviço trata 404 como sessão já apagada, então uma chave restrita deixaria imagens guardadas sem aviso.
  • Ponha VARANDA_DIDIT_API_KEY e VARANDA_DIDIT_WORKFLOW_ID no .env. O teto diário opcional é VARANDA_DIDIT_DAILY_LIMIT (padrão: 200 sessões por dia).
  • Em produção, defina as duas variáveis. Sem elas ninguém é consultado (útil só no desenvolvimento e na demo) e o serviço registra isso na partida. Para desligar, remova as duas.
  • Defina VARANDA_AGE_SINCE com o momento em que a verificação de idade passou a valer nesta instalação, em ISO (por exemplo 2026-10-29T00:00:00.000Z), nunca antes. O app lê esse momento em GET /account/age/since, num atestado que o emissor assina na hora e que vale só para certificados datados até a assinatura (a rota responde null até existir a primeira faixa ou enquanto o serviço não tiver certificado de emissor), guarda o atestado no nó, que confere a assinatura a cada leitura, e trata como já verificada a conta cujo certificado de membro tem data entre o since assinado e o momento da assinatura (um certificado fora desse intervalo não conta), em qualquer aparelho, sem pedir a idade de novo. Uma data anterior liberaria certificados emitidos sem checagem. O serviço nunca serve um since anterior ao início do dia UTC seguinte à primeira faixa registrada, nem à última vez em que a checagem foi ligada, nem ao certificado mais recente de um membro vinculado sem faixa (lido do diretório a cada início): a cada início ele grava em age-check.json, no volume account-data (modo 0600), se a checagem está ligada e desde quando. Inclua o arquivo no backup; se ele estiver inválido, a rota responde 503 indisponivel até a operação corrigir o arquivo ou restaurar a cópia mais recente. Com a checagem desligada, um início que não consegue gravar o arquivo termina com erro. A variável exige as duas do Didit: definida com a checagem desligada, o serviço não sobe, porque com a checagem desligada ele emite certificados sem faixa. Se a verificação for desligada, remova a variável, e ao religar use o novo momento.

No app e na web hospedada, a resposta verificado traz uma prova assinada pelo emissor (a chave do membro e a data da faixa registrada, nunca a faixa, a foto ou o documento), que o app guarda no nó; o nó confere a assinatura a cada leitura. O registro do aparelho guarda só recusas. Uma conta cujo certificado de membro tem data igual ou posterior ao since assinado entra direto em qualquer aparelho, mesmo sem essa prova. Nos dois casos o app confere com o serviço em segundo plano e mostra a etapa de idade de novo se a resposta for outra.

O que fica guardado: o age.json no volume account-data (modo 0600), com a chave do membro, a faixa (16-17 ou 18+), o método didit e a data. Nada além disso. Faça o backup junto com o resto do account-data. A imagem do rosto e o documento nunca chegam ao Varanda.

Retenção no Didit: depois de cada decisão final o serviço pede ao Didit que apague a sessão (DELETE com retain_face_embeddings falso). Se falhar, tenta de novo algumas vezes, em memória. Como reserva, defina a retenção mínima no console do Didit e recuse ali qualquer uso para treinamento ou reaproveitamento.

Limites: 3 sessões por membro em 24 h e, para quem ainda não tem vínculo, 3 por código de convite em 24 h (com convites ligados). O teto diário conta à parte as chaves novas e os membros já vinculados, então chaves descartáveis não tiram a vez de quem já é membro. Com o cadastro aberto (sem convites), só o teto diário segura chaves descartáveis: acompanhe o registro idade/sessao e use convites se o teto encher. As sessões pendentes ficam só na memória, então um reinício pede que a pessoa recomece e a sessão aberta não é apagada no Didit (a retenção mínima do console cobre esse caso). Uma estimativa por rosto abaixo de 21 anos pede o documento, e só o documento pode recusar (menos de 16).

Teste de fumaça no sandbox, ANTES de ligar em produção. O serviço falha fechado (todos continuam bloqueados) se o formato das respostas do Didit for diferente do esperado. Com uma chave de sandbox e o id do seu workflow:

curl -sS -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: $VARANDA_DIDIT_API_KEY" \
  -H "content-type: application/json" \
  -d "{\"workflow_id\": \"$VARANDA_DIDIT_WORKFLOW_ID\", \"callback\": \"https://<domínio>/?idade=volta\"}"
curl -sS https://verification.didit.me/v3/session/<id>/decision/ \
  -H "x-api-key: $VARANDA_DIDIT_API_KEY"

Confira que as respostas trazem session_id, url e um campo status.

Diagnóstico: quando o app mostra "A verificação de idade está fora do ar agora", o serviço registra o motivo, só com palavras fixas (nunca a chave, a sessão ou o que o Didit respondeu). Veja com docker compose -f deploy/seeder/compose.yaml -f deploy/seeder/compose.web.yaml logs account | grep '"idade"':

Registro (reason) O que fazer
didit-sessao-http-401 ou didit-sessao-http-403 Chave recusada: confira VARANDA_DIDIT_API_KEY (de produção, não de sandbox), os privilégios e se há crédito na conta do Didit.
didit-sessao-http-400 com didit-sessao-campo-callback O domínio do callback não está liberado no Didit: ponha a origem pública nos domínios permitidos da aplicação.
didit-sessao-http-400 ou -404 com didit-sessao-campo-workflow_id O VARANDA_DIDIT_WORKFLOW_ID não existe para essa chave.
didit-sessao-tempo ou didit-sessao-rede O servidor não alcançou verification.didit.me (rede, DNS, firewall de saída).
didit-sessao-formato O Didit respondeu num formato inesperado: rode o teste de fumaça acima e compare.
armazenamento-indisponivel O age.json não pôde ser lido ou gravado no volume account-data.
estado-indisponivel O age-check.json (quando a verificação foi ligada pela última vez) não pôde ser lido ou gravado no volume account-data, ou o diretório e as faixas não puderam ser lidos ao subir; GET /account/age/since responde 503 até o arquivo voltar a valer e o serviço reiniciar.
teto-diario O teto VARANDA_DIDIT_DAILY_LIMIT encheu; volta no dia seguinte.

Os mesmos motivos, com didit-decisao- no lugar de didit-sessao-, valem para a leitura do resultado.

Antes do lançamento é preciso existir um canal privado de contato para contestação da decisão. Defina-o com os mantenedores; este documento não inventa um.

Verificação de celular (serviço account)

Com VARANDA_PHONE_KEY definida, todo membro hospedado confirma um celular brasileiro antes do vínculo, da troca de @nome, dos convites, do push, da gravação de lidas, da criação de página e dos códigos da Feira (a recusa é telefone-pendente). A pessoa digita o número, recebe um código de 6 dígitos por SMS (nunca por WhatsApp) enviado pelo Didit, com a mesma chave da API da verificação de idade, e o digita no app. A faixa de idade vem antes: ela é o freio dos envios pagos.

O que fica guardado: o phone.json no volume account-data (modo 0600), com a chave do membro, o número selado (AES-256-GCM, preso à chave do membro), um índice com chave (HMAC) que serve para a unicidade e para os bloqueios, a data da verificação e, quando houver, o fim (trocado, excluida, substituido, liberado). O número nunca vai para os certificados, para a camada P2P, para respostas a outros membros, para os registros, para o painel de moderação nem para o account export. O serviço assina com a chave do emissor um atestado phone-verified (a chave do membro e a data, nunca o número), que o app guarda no nó, para a versão hospedada abrir sem rede; o atestado só é devolvido quando o serviço tem emissor (sem emissor, a verificação vale mas não vem atestado). Se a chave do emissor vazar e for revogada (mod revoke-issuer), os atestados que ela assinou também deixam de valer.

Backup: o phone.json e a VARANDA_PHONE_KEY vão juntos no backup, guardados em lugares separados. Perder a chave é perder todos os números e todos os bloqueios: o serviço falha fechado (o phone.json não abre, a etapa responde indisponivel e ninguém consegue se verificar) até a operação restaurar a chave certa. Trocar a chave não é suportado: com outra chave o arquivo não abre e nunca é regravado.

Limites: 5 envios por membro por dia, 3 por número por dia, 60 s entre envios e o teto diário VARANDA_PHONE_DAILY_LIMIT (padrão 200, à parte para chaves vinculadas e não vinculadas). No dia em que os membros já vinculados passarem a verificar, suba o teto para esse dia. Um número já verificado por outra conta vinculada é recusado (telefone-em-uso); o de uma conta bloqueada pela moderação fica preso enquanto o bloqueio durar.

Registros: o evento telefone traz só palavras fixas, nunca o número, o código ou a chave. Na partida, ligada ou desligada; indisponivel (o phone.json não abriu com esta chave, a verificação continua exigida e a etapa fica fechada); arquivo-sem-chave (há um phone.json mas a chave não está definida, então nenhuma retenção corre). Em uso: enviado, verificado, em-uso, recusado-linha (fixo, VoIP ou descartável), tipo-desconhecido (aceito, tipo de linha que o serviço não conhece), teto-diario, armazenamento-indisponivel, gravacao-falhou, varredura-falhou, varredura-exclusao-falhou, resultado-desconhecido, didit-envio-bloqueado e, para falhas do Didit, didit-envio- ou didit-checagem- seguido de falha (a resposta do Didit não foi aceita), http-NNN, tempo, rede, formato ou entrada (com -campo-<nome> para cada campo que o Didit apontou). Veja com docker compose -f deploy/seeder/compose.yaml -f deploy/seeder/compose.web.yaml logs account | grep '"telefone"'.

O comando account phone --member <chave> mostra os números verificados de um membro, para uma ordem judicial ou para o pedido de acesso do próprio membro (LGPD). Precisa da VARANDA_PHONE_KEY no ambiente, roda só no servidor (pode rodar com o serviço no ar), não tem rota HTTP, não registra nada e imprime uma linha JSON { member, rows }. Essa saída nunca é colada em issue, chat ou e-mail: entregue-a pelo canal que a ordem ou o pedido indicar. Quando a ordem traz um nome e não uma chave, account phone --username <nome> (com ou sem @) acha a conta que teve o nome, atual ou passada: um nome que já foi de um membro nunca vai para outro, então sai no máximo uma linha JSON { username, key, kind, current, deletedAt, phone }, com kind membro ou excluido, current dizendo se a conta ainda usa o nome e phone com as mesmas linhas do --member (lista vazia se não houver número). Para uma página (kind pagina) a linha traz owner, a chave de quem a tem, e nenhum número, e a VARANDA_PHONE_KEY não é lida; se o pages.json registra a mudança de chave da página, vem também movedTo (a dona é a da época da mudança), e uma página sem registro no pages.json dá "página sem registro em pages.json". Um nome que nunca foi emitido dá "nome não encontrado".

Ordem da implantação inicial da verificação de celular (antes de feat/retire-google-member-link; para retirar o vínculo Google, siga a ordem em "Vínculo de conta Google e @nome"):

  1. Implante esta versão do serviço com VARANDA_PHONE_KEY vazia. Nada muda para ninguém.
  2. Rode a lista do sandbox abaixo.
  3. Espere a versão web e a versão do app (atualização na loja) com a etapa do celular estarem no ar e serem as que os membros usam. Versões antigas não têm a tela nem o phone.sign, e seriam recusadas no cadastro.
  4. Só então defina VARANDA_PHONE_KEY e reinicie o account.

Resíduo conhecido: um app nativo instalado mais antigo que a etapa do celular não consegue mostrá-la. O serviço recusa a ele o vínculo, a troca de @nome, os convites, o push, a gravação de lidas, a criação de página e os códigos da Feira, mas ele continua publicando no próprio diário pela rede P2P, porque certificados não vencem. Por isso a chave só entra depois que a atualização da loja estiver no ar.

Para desligar de vez: remova a chave e apague o phone.json. Remover só a chave deixa o arquivo parado, sem retenção (o registro arquivo-sem-chave lembra disso a cada partida).

Lista do sandbox, ANTES de definir a chave (o serviço falha fechado se as respostas do Didit vierem num formato diferente do esperado). Com a mesma chave da API e sem id de workflow:

curl -sS -X POST https://verification.didit.me/v3/phone/send/ \
  -H "x-api-key: $VARANDA_DIDIT_API_KEY" -H "content-type: application/json" \
  -d '{"phone_number": "+55<número de teste>", "vendor_data": "<texto aleatório>", "options": {"preferred_channel": "sms", "locale": "pt-BR", "code_size": 6}}'
curl -sS -X POST https://verification.didit.me/v3/phone/check/ \
  -H "x-api-key: $VARANDA_DIDIT_API_KEY" -H "content-type: application/json" \
  -d '{"phone_number": "+55<número de teste>", "code": "123456", "voip_number_action": "DECLINE", "disposable_number_action": "DECLINE", "duplicated_phone_number_action": "NO_ACTION"}'

Confira e anote:

  • o envio e a checagem com o código de sandbox 123456 respondem status (Success no envio, Approved na checagem);
  • a resposta antes da primeira recarga de crédito (401 ou 403);
  • se um Retry no envio é cobrado (a documentação da Didit diz que Retry reenvia o código da verificação pendente, e o serviço o trata como enviado);
  • os status de um código errado e das tentativas esgotadas (hoje Failed vira codigo-invalido, Expired or Not Found vira codigo-expirado, e Declined sem sinal de linha vira codigo-expirado; confira se um número em lista de bloqueio do Didit também chega como Declined);
  • o carrier.type de um celular brasileiro real e o country_code que volta para ele;
  • o que um envio para um número VoIP responde (status e campos do corpo do 400);
  • se existe rota para apagar registros de telefone no Didit (hoje o serviço não chama nenhuma);
  • que preferred_channel: "sms" entrega por SMS e nunca por WhatsApp;
  • o preço de um envio de SMS para um número brasileiro.
Ordem judicial: desbloqueio e liberação do número
  1. A conta ainda existe e a ordem levanta o bloqueio: rode mod unblock <chave> num terminal (ele publica a lista). O número deixa de ficar preso na próxima varredura, na partida ou em até uma hora, e, se o bloqueio durou menos de 180 dias, o membro fica com a conta e com o número; passados os 180 dias o número selado já foi apagado e o membro precisa verificar de novo (telefone-pendente). Um membro bloqueado pela operação continua com o número preso mesmo depois de excluir a conta; só mod unblock (ou um recurso aceito) seguido de uma varredura o solta.
  2. A conta não pode voltar (a pessoa a excluiu, ou a ordem libera só o número): pare o serviço account, rode account phone --release --member <chave> com a VARANDA_PHONE_KEY no ambiente e suba o serviço de novo. O comando toma a mesma trava do serviço, então recusa com o serviço no ar ("pare o serviço de conta antes de liberar um número"), imprime só { member, released: true, rows }, nunca o número, e não mexe na moderação. Rodar de novo para confirmar é seguro: um membro já liberado responde com alreadyReleased: true, mesmo depois que a retenção apagou as linhas dele, e só uma chave sem número nem liberação dá "sem telefone registrado". Se a gravação falhar, a liberação pode ou não ter valido: confira com account phone --member <chave> antes de rodar de novo e não conserte nem apague o phone.json. Depois disso o número pode ser confirmado por outra conta, a chave antiga continua bloqueada e o número selado fica guardado por até 180 dias. account phone --member precisa da chave do membro; account reports --member só filtra por uma chave que você já tem. Para descobrir a chave, use account reports sem --member (lista só quem foi denunciado) ou a lista pública de bloqueios (mod show --json), que traz também quem foi bloqueado sem denúncia.

Páginas (opcional, serviço account)

Páginas são diários de empresa ou projeto, com @nome próprio, administrados por membros. O serviço account guarda a chave de cada página e é o único que assina e grava no diário dela. Quem administra age por pedidos assinados com a chave do próprio diário e nunca recebe a chave da página.

Desligadas por padrão. Para ligar, defina em deploy/seeder/.env (reinicie o serviço account):

  • VARANDA_PAGE_KEYS: 64 hex minúsculos, gerados com openssl rand -hex 32. Sem ela, o serviço não abre o arquivo de chaves nem o escritor das páginas, e o registro mostra paginas desligada.
  • VARANDA_SEEDER_WS: ws://127.0.0.1:<porta>, a porta de WebSocket do semeador (VARANDA_WS_PORT). Obrigatória com a chave.

Backup e restauração da chave:

  1. O valor mora em /etc/varanda/varanda.env (servidor atualizado por imagem) ou em deploy/seeder/.env. É uma chave de dados deste servidor: não se sela nem se divide com outro servidor (veja "Segredos", acima).
  2. Guarde-o à parte e junto com cada backup do volume account-data, em cofre separado do volume. O page-keys.json não abre sem o valor, e o valor sozinho não serve sem o arquivo.
  3. Ao restaurar, ponha o page-keys.json no volume e o mesmo valor no .env, e reinicie o serviço account. Confira no registro: { event: 'paginas', reason: 'ligada' } quer dizer que abriu. reason: 'indisponivel' quer dizer que as páginas não abriram: pode ser o page-keys.json que não abre com a chave dada, o pages.json que não abre ou a trava do serviço perdida. Nada é reescrito, o serviço sobe sem páginas, e nenhum valor é impresso. Se foi a chave, confira o valor do .env contra o cofre.
  4. Trocar o valor não é suportado: uma chave nova não abre o arquivo antigo. Para mudar de servidor, leve o valor e o arquivo juntos.

Ao iniciar, o serviço de conta encerra no diretório as páginas que não têm diário de página nem registro de administração (uma criação interrompida entre a reserva do @nome e o diário); o log traz { event: 'paginas', reason: 'orfas-encerradas', count }, e orfas-pendentes se a limpeza falhou. VARANDA_NO_PAGE_MIGRATE=1 vale só para o nó core.

O que fica no volume account-data:

  • page-keys.json: as chaves das páginas, cifradas com AES-256-GCM sob VARANDA_PAGE_KEYS; modo 0600. Nada é impresso nem registrado.
  • pages.json: a lista de controle das páginas (dono, administradores, convites pendentes, encerramento e mudança), sem nenhuma chave secreta; modo 0600.
  • pages-store/: os diários das páginas e as cópias das fotos.
  • pages-groups/ e pages-replicas/: os núcleos de escritor das páginas em comunidades e grupos (só chaves públicas) e as cópias dos grupos que elas leem. Os segredos de escritor ficam em page-keys.json; a caixa dos grupos privados deriva dos segredos da Página guardados nos aparelhos administradores.
  • page-invite-rosters.json e page-nonce-key.json: convites pendentes e a chave que autentica os nonces, modo 0600.

Regras de operação:

  • As páginas dividem o inventário do semeador, com no máximo 256 páginas no total.
  • Uma página pode publicar fotos nas publicações e seguir outras contas, por ação do dono ou de um administrador.
  • Encerrar a página é definitivo: o @nome fica reservado e nunca é emitido de novo. O serviço continua servindo a página encerrada, só para leitura, e apaga as chaves dela depois que o semeador recebeu o encerramento (isso é refeito depois de um reinício). Cada dono faz no máximo 2 encerramentos ou mudanças de chave a cada 24 h (a contagem fica no pages.json e vale também depois de um reinício). Para uma chave vazada, mod block da chave da página é o remédio do operador.
  • Mudar a chave de uma página publica uma declaração sucessora, assinada pela chave antiga, que aponta para a nova. Quem segue a página vê a troca nessa declaração.
  • Páginas em comunidades ficam ligadas sempre que as páginas estão ligadas. Não há interruptor separado. O serviço não guarda a chave das mensagens nem a caixa dos grupos privados da página: assina somente os digests das Conversas e acrescenta blocos de grupo já selados, sem ver o conteúdo. A caixa privada fica nos aparelhos administradores. É exceção a época antiga conhecida pelo serviço antes da renovação da caixa. O serviço ainda lê os avisos endereçados à página em nome de quem a administra. Termos e Política na versão 34.
  • Um nó core administra páginas com uma chave de delegado guardada no aparelho. A CLI usa VARANDA_ACCOUNT_ORIGIN (https) e o varanda-serve --account-origin https://<host> liga as Páginas no app servido por ele. O VARANDA_NO_PAGE_MIGRATE=1 desliga o acompanhamento automático da chave nova de uma página nos aparelhos de quem segue.
  • O serviço confere com a lista curta da conferência de palavras do app o @nome novo de uma página (nome-invalido) e o que ela publica por ele, a publicação, a resposta, a citação, o perfil, o anúncio e a mensagem em grupo público (termo-recusado), sem gravar nada e sem registrar o texto. Um @nome que a página já tem não é conferido de novo, nem numa mudança de chave.
  • Criar a primeira página é uma migração de mão única do diretório de contas (ver o parágrafo sobre voltar a versões anteriores em "Vínculo de conta Google e @nome").

Implantação automática pelo GitHub Actions

O fluxo deploy (.github/workflows/deploy.yml) implanta main no servidor a cada push. Ele repete as checagens do CI (npm ci, lint, testes e demo) como os mesmos oito jobs em paralelo, no Node 24. O job check reúne os oito e só passa se todos passaram. Se check passar, o fluxo entra no servidor por SSH como varanda-deploy e roda deploy/seeder/deploy.sh. O SHA testado vai pela entrada padrão do SSH, nunca por argumento.

O job deploy usa o ambiente producao. Se o ambiente pede a aprovação de um revisor, só a execução mais nova espera por ela: antes da aprovação, o job supersede cancela as execuções mais antigas de main que ainda esperam, e uma execução que chega lá depois de uma mais nova ter começado termina verde sem implantar. Uma implantação que já começou nunca é cancelada: a seguinte espera ela terminar. Por isso o fluxo não tem concorrência própria, e as checagens de dois pushes seguidos podem rodar ao mesmo tempo. Os fluxos ios-release e site têm o mesmo job.

O script só implanta se esse SHA for a ponta de origin/main. Se main já avançou, sai com 3 e o fluxo termina verde com um aviso: a execução mais nova de main implanta (se nenhuma estiver na fila, use Run workflow). Ele recusa, sem mudar nada, um checkout com alterações locais ou com commits que não estão em origin/main, e um VARANDA_DOMAIN que não seja um nome em minúsculas sem ponto final. Depois ele:

  • guarda a imagem que o semeador está rodando (etiquetada varanda-seeder:anterior) e uma cópia do deploy/seeder/www em /var/lib/varanda-deploy; o commit que está no ar fica anotado em /var/lib/varanda-deploy/implantado desde a última implantação;
  • atualiza o checkout e gera o app web (build-web.sh) numa cópia exportada do commit (.deploy-build/, nunca no checkout, e como o usuário nobody, nunca como root: os scripts de instalação das dependências não podem reescrever os compose, o Caddyfile nem deixar nada com poder de root no servidor); o deploy.sh passa o commit ao build web (EXPO_PUBLIC_VARANDA_COMMIT, embutido no bundle junto com EXPO_PUBLIC_VARANDA_BUILD_DATE por scripts/resolve-build-info.js); o build e o deploy.sh conferem que sw.js foi gerado, e o build, que o index.html tem a marca varanda-release e que existe a cópia do nó com esse nome (varanda-node-<versão>.js);
  • constrói a imagem do semeador e a do Caddy (deploy/seeder/Dockerfile.caddy: o Caddy oficial por digest mais o módulo caddy-ratelimit em versão fixa, que limita /index/* e /media/* por cliente; a anterior fica guardada como varanda-caddy:anterior), copia o app para www (só arquivos e diretórios comuns: um link simbólico deixado pelo build é recusado; o index.html entra por último, depois do sw.js, para que uma página nova nunca chegue antes do nó que ela carrega), e depois da cópia reescreve www/version.json a partir do SHA conferido, e sobe o semeador e o Caddy;
  • confere a saúde: /health do semeador com 200 em até 180 s, o index.html e o varanda-node.js servidos pelo domínio byte a byte iguais aos de www em até 60 s, também sw.js quando existe em www, o bundle com hash citado no index.html e a cópia do nó com o nome da versão marcada nele (varanda-node-<versão>.js), e /version.json quando existe em www (o arquivo servido comparado à cópia de www), /varanda.json com o corpo exato {"v":1,"association":"<VARANDA_ASSOCIATION>"} e um WebSocket de verdade aberto em wss://<domínio>/seeder com o Origin de produção; a primeira implantação depois desta mudança ainda executa o deploy.sh anterior, então a sonda de sw.js só roda a partir da segunda; o mesmo vale para a sonda da cópia do nó e para a cópia com o index.html por último; a primeira implantação com esta mudança de /version.json também roda o deploy.sh anterior, publica o arquivo pela cópia do build (o build-web.sh novo o grava no dist e o cp antigo o leva para www) e pula a sonda nova (confira com curl https://<domínio>/version.json); a volta restaura o arquivo anterior ou a ausência dele;
  • se algo falhar (ou se receber Ctrl-C ou SIGTERM no meio), volta sozinho para o commit, as imagens (semeador e Caddy) e o www anteriores (com o index.html de novo por último), sem reconstruir nada, e sai com 1. Só reinicia o semeador e o Caddy se eles já tinham sido trocados: uma falha no build não derruba nada. Os últimos registros do semeador e do Caddy ficam em /var/lib/varanda-deploy/deploy.log.

Antes de aplicar a mudança que traz o /varanda.json: acrescente VARANDA_ASSOCIATION=<64 hex> ao deploy/seeder/.env do servidor. A primeira implantação com essa mudança roda o deploy.sh anterior (o bash já leu o arquivo inteiro antes do git reset), sem a sonda do /varanda.json; sem o valor no .env, o compose recusa subir, a implantação falha e volta sozinha. O deploy.sh novo também recusa, antes de mudar qualquer coisa, um VARANDA_ASSOCIATION ausente ou que não tenha 64 dígitos hexadecimais. Depois da primeira vez, confira à mão com curl https://<domínio>/varanda.json.

O semeador e o Caddy ficam fora do ar por alguns instantes a cada implantação. Ao receber SIGTERM, o semeador fecha as conexões dos apps com o código 1012 ("reiniciando") e o Caddy repete a discagem por até 5 s enquanto a porta do semeador está fechada; o semeador novo aceita os apps assim que prepara os diários, antes de terminar a partida, e segura por até 8 s uma conexão que chega antes disso. Nesse intervalo os apps seguem respondendo com os dados locais, recusam publicar na hora ("sincronize com o semeador antes de publicar") e voltam a conectar em alguns segundos: depois de um 1012 a nova tentativa sai em 0,5 a 1,5 s e, nos primeiros 3 minutos de qualquer outra queda, em cerca de 5 s depois que o semeador responde de novo. Até o semeador terminar a partida, a descoberta responde defasada e as páginas de índice dizem que ainda estão indexando. Abrir ou trazer o app para o primeiro plano no meio da implantação ainda pode custar uma partida. A volta não desfaz mudanças de formato dos dados que a versão nova já tenha gravado. O registro fica em /var/lib/varanda-deploy/deploy.log. O log do fluxo mostra só as mensagens do script; a saída do build e do docker fica no servidor, porque o log do GitHub Actions de um repositório público é público. O deploy/seeder/.env não faz parte da implantação nem da volta: a volta sobe a versão anterior com o .env que estiver no servidor. Para trocar o domínio, faça como na seção anterior, à mão, e confira o site antes da próxima implantação. Se a ponta de main já estiver no ar e saudável, o script só confere a saúde e sai com 0 sem reiniciar nada; para forçar uma nova implantação, apague /var/lib/varanda-deploy/implantado. O checkout (/opt/varanda, deploy/, deploy/seeder/, o deploy.sh, o .git e o .git/config) precisa ser de root e sem escrita para grupo ou outros, porque o sudoers dá root a esse arquivo e root roda git ali; senão o script recusa. Códigos de saída: 0 implantado, 1 falha (nada mudou ou voltou), 2 uso errado, 3 main já avançou.

Antes: o semeador e a versão web no ar à mão, como nas seções anteriores (o script exige deploy/seeder/.env, o semeador rodando e o app publicado em deploy/seeder/www). Os passos abaixo são todos seus (do usuário); o fluxo fica pulado até o passo 9. Troque <ip> pelo endereço do servidor e AAAA… pela chave pública gerada no passo 3.

  1. Faça o merge do pull request. Sem a variável VARANDA_DEPLOY (passo 9), o fluxo não faz nada.

  2. Como root no servidor, atualize o checkout e crie o usuário:

    git -C /opt/varanda pull
    useradd --system --create-home --shell /bin/bash varanda-deploy
    install -d -o varanda-deploy -g varanda-deploy -m 0700 /home/varanda-deploy/.ssh

    Se o sshd usa AllowUsers, acrescente varanda-deploy a ele e recarregue o serviço. Confira que o checkout é de root e sem escrita para grupo ou outros (cada linha deve mostrar root e um modo como 755; o script recusa rodar senão):

    stat -c '%U %a %n' /opt/varanda /opt/varanda/deploy /opt/varanda/deploy/seeder /opt/varanda/deploy/seeder/deploy.sh /opt/varanda/.git /opt/varanda/.git/config
  3. Na sua máquina, gere um par de chaves só para isso:

    ssh-keygen -t ed25519 -N '' -C varanda-deploy -f varanda-deploy-key
    cat varanda-deploy-key.pub
  4. No servidor, grave em /home/varanda-deploy/.ssh/authorized_keys (modo 0600, dono varanda-deploy) esta linha, com a chave pública do passo 3:

    restrict,command="sudo -n /opt/varanda/deploy/seeder/deploy.sh" ssh-ed25519 AAAA… varanda-deploy
    

    O command= faz essa chave rodar só o script, e o restrict desliga encaminhamentos e pty.

  5. No servidor, crie /etc/sudoers.d/varanda-deploy (modo 0440) com esta linha e confira com visudo -c:

    varanda-deploy ALL=(root) NOPASSWD: /opt/varanda/deploy/seeder/deploy.sh ""
    

    O "" proíbe qualquer argumento.

  6. Monte a linha de known_hosts com a chave do próprio servidor, lida numa sessão em que você já confia (nunca de um ssh-keyscan sem conferência):

    echo "varanda-producao $(cut -d' ' -f1,2 /etc/ssh/ssh_host_ed25519_key.pub)"

    O resultado tem a forma varanda-producao ssh-ed25519 <chave>. Guarde essa linha para o passo 8.

  7. Teste à mão, da sua máquina (use um known_hosts seu, com a mesma chave conferida). A entrada vazia implanta a ponta de main:

    ssh -T -i varanda-deploy-key varanda-deploy@<ip> </dev/null

    Deve terminar com implantado <sha>. Este teste também cria o registro da versão em produção: sem ele, a primeira implantação automática logo depois de um git pull manual não tem como saber o que está no ar, loga sem registro da versão em produção e usa o HEAD do checkout como ponto de volta.

  8. No GitHub, Settings > Environments > New environment producao:

    • Deployment branches and tags: só main;
    • Secret DEPLOY_SSH_KEY: o conteúdo de varanda-deploy-key;
    • Variable DEPLOY_HOST: o endereço do servidor (só letras, números, . e -);
    • Variable DEPLOY_KNOWN_HOSTS: a linha do passo 6.

    Depois apague a chave privada da sua máquina (o macOS não tem shred):

    rm -f varanda-deploy-key
  9. Em Settings > Secrets and variables > Actions > Variables, crie VARANDA_DEPLOY com o valor true. Qualquer outro valor pausa as implantações.

  10. Em Actions > deploy > Run workflow, na branch main, rode a primeira implantação e acompanhe o log.

Uma chave vazada só consegue pedir a implantação da ponta de main: se ela já estiver no ar e saudável, nada é reiniciado. Não escolhe o commit nem lê a chave do semeador, o volume, o .env ou a chave da associação. Para trocar a chave, substitua o authorized_keys e o segredo DEPLOY_SSH_KEY.

Quem tem o servidor de fato é quem faz merge em main: os compose, o Dockerfile e o build-web.sh vêm do checkout e rodam como root. A proteção é a regra de main (revisão, code owners e os checks test (20) e test (24)).

Se a conexão SSH cair, o script termina sozinho; leia /var/lib/varanda-deploy/deploy.log. Alterações locais em /opt/varanda barram a implantação (alterações locais): guarde-as ou descarte-as. Para repetir, use Run workflow, não Re-run de uma execução antiga: um Re-run pode deslocar uma execução mais nova que está esperando, e ela sai com 3. Recuperação à mão, como root no servidor: bash deploy/seeder/deploy.sh </dev/null (da raiz do repositório), e docker compose -f deploy/seeder/compose.yaml -f deploy/seeder/compose.web.yaml logs.

Um servidor que atualiza por imagem não usa este caminho: veja a próxima seção, "Atualização por imagem (pull)"; o deploy.sh recusa um servidor que migrou.

Atualização por imagem (pull)

Em vez de o GitHub entrar no servidor por SSH, cada servidor baixa imagens assinadas do GHCR e se atualiza sozinho: ninguém guarda uma chave SSH por servidor. O fluxo release (.github/workflows/release.yml) publica ghcr.io/varanda-org/varanda-seeder e ghcr.io/varanda-org/varanda-web (só amd64) depois de cada main verde e as assina; o fluxo promote (.github/workflows/promote.yml) move o canal stable para uma versão já publicada. update.sh (deploy/seeder/update.sh), disparado por um timer do systemd, faz o resto no servidor. Só precisa de Docker com o plugin compose v2, curl, flock e systemctl: sem git, sem Node e sem jq.

Canais: stable (padrão) só muda quando alguém aprova um promote no ambiente release-stable; edge segue cada main verde. Modos, escolha obrigatória e sem padrão: VARANDA_UPDATE=auto aplica sozinho cada versão nova assinada do canal; VARANDA_UPDATE=manual só avisa no registro e espera update.sh apply. Perfis: seeder (padrão) sobe só o semeador; full sobe também o Caddy com o app web e o serviço de conta (e exige /etc/varanda/varanda.env).

Confiança, sem rodeio. As imagens são públicas e não levam segredo nenhum. Cada versão é assinada sem chave guardada (cosign keyless, pelo OIDC do GitHub Actions) com uma destas identidades, emitidas por https://token.actions.githubusercontent.com: https://github.com/Varanda-org/varanda/.github/workflows/release.yml@refs/heads/main (edge) e https://github.com/Varanda-org/varanda/.github/workflows/promote.yml@refs/heads/main (stable, que ainda passa pela aprovação humana). O atualizador confere a assinatura antes de usar qualquer coisa da imagem, com o cosign fixado em deploy/seeder/cosign.ref (nunca o da imagem candidata), recusa uma versão com seq mais antigo e troca os próprios scripts pelos da imagem conferida. Logo, quem consegue fazer merge em main manda nos servidores, como já acontece no deploy por SSH acima; o stable só acrescenta uma aprovação.

1. Primeira conferência, obrigatória, antes de rodar qualquer coisa da imagem como root. O update.sh que vai rodar sai da própria imagem, então a primeira cópia dele precisa ser conferida à mão. Como root no servidor, com o plugin docker buildx instalado (para edge, troque a etiqueta por edge e a identidade pela do release.yml):

repo=ghcr.io/varanda-org/varanda-seeder
digest=$(docker buildx imagetools inspect "$repo:stable" | sed -n 's/^Digest: *//p' | head -n 1)
echo "$digest"   # sha256:<64 hex>

docker run --rm --read-only --cap-drop ALL --security-opt no-new-privileges \
  --tmpfs /cosign-home:rw,nosuid,nodev,noexec,size=64m,mode=1777 -e HOME=/cosign-home \
  ghcr.io/sigstore/cosign/cosign:v3.1.4@sha256:0f06154836d2de34f887a5c273506d52ca43edaa1d9e53e6510fa78a48f69c2d verify \
  --certificate-identity https://github.com/Varanda-org/varanda/.github/workflows/promote.yml@refs/heads/main \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  "$repo@$digest" >/dev/null && echo 'assinatura conferida'

Só continue se imprimiu assinatura conferida. Confira também que o commit e o seq de /app/release.json dessa imagem (docker run --rm --network none --entrypoint cat "$repo@$digest" /app/release.json) batem com o resumo da execução do promote (no stable) ou do release (no edge): uma etiqueta sozinha pode ser movida por qualquer execução de fluxo com packages: write. Depois extraia o pacote DESSE digest (nunca de uma etiqueta lida de novo) para um diretório de root, sem escrita para grupo ou outros (o update.sh recusa rodar de outro jeito):

cid=$(docker create --network none --entrypoint cat "$repo@$digest")
docker cp "$cid:/app/deploy/seeder" /root/varanda-bootstrap
docker rm "$cid"

Configure (passo 2) e rode cd /root/varanda-bootstrap && ./update.sh install --image "$repo@$digest". O install confere de novo a assinatura e o digest, mas é só uma segunda linha de defesa: não substitui este passo.

2. Configuração. /etc/varanda/update.conf, a partir de deploy/seeder/update.conf.example: uma linha NOME=valor por variável, sem aspas, lido e nunca executado, com VARANDA_UPDATE (obrigatória), VARANDA_CHANNEL (stable ou edge) e VARANDA_PROFILE (seeder ou full). Sem VARANDA_UPDATE o update.sh sai com 2. /etc/varanda/varanda.env é o deploy/seeder/.env do servidor (variáveis em deploy/seeder/.env.example): dono root, modo 0600, arquivo comum. É obrigatório no perfil full e opcional no seeder; quando existe, o pré-voo confere antes de tocar em qualquer coisa que roda as mesmas regras que o deploy.sh conferia (no full: domínio, associação, cliente do Google, moderadores e limites do serviço de conta; nos dois perfis: as origens e os limites do semeador), e um arquivo recusado barra a troca. Um valor local não vazio é o que os serviços recebem.

3. O que o install faz. Exige root, amd64 (x86_64), o plugin compose v2 e systemctl. Num servidor novo (nenhum contêiner do projeto varanda-seeder): prepara a versão em /opt/varanda-release/<commit>, aponta /opt/varanda-release/current para ela e não inicia nada; faça antes a chave e o certificado do semeador como na seção "Docker Compose", trocando docker compose -f deploy/seeder/compose.yaml por /opt/varanda-release/current/update.sh compose (por exemplo update.sh compose run --rm seeder seed key --association "$ASSOC"), e então rode update.sh apply. Num servidor que vem do deploy por SSH: confere o checkout de onde o semeador roda (o diretório e cada ancestral, e compose.yaml, compose.web.yaml, Caddyfile e .env, precisam ser de root e sem escrita para grupo ou outros), guarda as imagens em execução como varanda-seeder:antes-do-pull e varanda-caddy:antes-do-pull, registra o checkout como versão anterior e aplica uma vez, em qualquer modo. Com o perfil seeder, recusa um servidor que roda o Caddy ou o serviço de conta (defina VARANDA_PROFILE=full e rode de novo). Em todo caso instala varanda-update.service e varanda-update.timer em /etc/systemd/system, habilita o timer na hora (enable --now) e grava o marcador /var/lib/varanda-deploy/modo-pull, que faz o deploy.sh recusar. O timer dispara três minutos depois do boot e a cada 15 minutos, com até 15 minutos de atraso aleatório, para os servidores não reiniciarem todos juntos; enquanto não houve o primeiro apply, cada disparo só registra "aguardando o primeiro apply". O estado fica em /var/lib/varanda-update (registro em update.log, até 5 MB mais uma geração .1; o journal recebe só as linhas de log: journalctl -u varanda-update), e as versões em /opt/varanda-release (só a atual e a anterior). Rodar install num servidor já instalado só atualiza as unidades.

4. No dia a dia (como root, /opt/varanda-release/current/update.sh):

  • status: modo, canal, perfil, versão instalada, disponível, preparada e anterior, e a intervenção pendente, se houver. Avisa quando as unidades do systemd diferem das da versão em uso.
  • check: baixa o canal, confere a assinatura e o seq e anota a versão disponível, sem trocar nada.
  • apply: aplica a versão do canal agora, em qualquer modo, e ignora as digests recusadas.
  • rollback: volta para a versão anterior (o servidor que veio do deploy por SSH volta ao checkout). O digest de que voltou também fica recusado. O ambiente efetivo da versão anterior volta inteiro: depois de um rollback (ou de uma volta automática), as edições de varanda.env feitas desde o último apply ou reconfigure daquela versão só valem com update.sh reconfigure.
  • reconfigure: depois de editar /etc/varanda/varanda.env, sobe de novo a mesma versão com as associações regravadas e confere a saúde, sem trocar de versão.
  • compose ps, compose logs -f seeder e demais argumentos: o docker compose da versão em uso, já com as imagens e o arquivo de ambiente certos.
  • run é o que o timer roda. Em manual só registra "nova versão disponível"; em auto prepara e aplica.

Toda troca (run em auto, apply, ou o primeiro apply do install) faz um pré-voo (arquivo de ambiente e docker compose config -q) antes de tocar no que roda, sobe a versão nova com up -d --no-build e só dá por concluída depois da verificação de saúde: /health do semeador com 200 em até 180 s e, no perfil full, o app, /varanda.json, /account/health e o painel de moderação servidos pelo domínio como esperado em até 60 s, um WebSocket de verdade em wss://<domínio>/seeder e cada serviço rodando a imagem da versão. Se algo falhar (ou chegar SIGTERM no meio), volta sozinho para a versão anterior (ou, num servidor que veio do deploy por SSH, ao checkout antigo) e sai com 1. Um digest que voltou fica em /var/lib/varanda-update/recusadas e, em auto, nunca é aplicado de novo; só um apply explícito o força. Códigos de saída: 0 feito ou nada a fazer, 1 falha (nada mudou ou voltou), 2 uso errado.

Intervenção. Se nem a volta funcionou (ou a versão nova subiu e saudável, mas o estado não pôde ser gravado), o update.sh grava o motivo em /var/lib/varanda-update/intervencao e o status o mostra. Enquanto o arquivo existir, run não troca nada: só registra "intervenção pendente" e sai com 1; check, status, reconfigure e compose continuam funcionando. Corrija a causa (o registro do servidor, em update.log, diz qual) e rode update.sh apply (com a versão instalada já em dia, ele a sobe de novo e, se ela passar na verificação, apaga o arquivo; com uma versão nova, a troca que dá certo o apaga) ou update.sh rollback (quando volta para uma versão instalada e dá certo, também o apaga). Uma exceção, de propósito: uma volta ao checkout antigo, automática (o primeiro apply falhou) ou por update.sh rollback, deixa a intervenção anotada. O servidor roda de novo o checkout, mas run não troca nada até você decidir. Nesse caso só um apply que dê certo (prepara a versão, troca e passa na verificação de saúde) apaga o arquivo; outro rollback volta ao checkout de novo e a anota outra vez.

5. Migrar um servidor que usa o deploy por SSH.

  1. Deixe o deploy por SSH implantar o commit que traz a recusa do modo pull (recusar_pull em deploy/seeder/deploy.sh).
  2. No GitHub, defina a variável VARANDA_DEPLOY com qualquer valor diferente de true (o fluxo deploy pausa).
  3. No servidor, copie deploy/seeder/.env para /etc/varanda/varanda.env, dono root, modo 0600, e crie /etc/varanda/update.conf (VARANDA_PROFILE=full se o servidor roda o Caddy).
  4. Faça a conferência do passo 1 e rode ./update.sh install --image "$repo@$digest".
  5. Confira com update.sh status e curl -s http://127.0.0.1:8788/health.

Se o primeiro apply falhar, o servidor volta sozinho aos contêineres do checkout antigo: o compose do próprio checkout com --no-build --force-recreate e as imagens antes-do-pull, nunca o deploy.sh (ele buscaria a ponta de main e reconstruiria). Isso deixa a intervenção anotada de propósito: o servidor fica sem atualização automática até você rodar update.sh apply (que a apaga se der certo). Para voltar de propósito ao deploy por SSH, desative o timer (systemctl disable --now varanda-update.timer) e apague /var/lib/varanda-deploy/modo-pull; o deploy.sh volta a funcionar. Depois que todos os servidores migrarem, remova o usuário varanda-deploy, a entrada dele no sudoers e o segredo DEPLOY_SSH_KEY.

6. Segredos. Nenhum segredo entra numa imagem em claro. As variáveis de /etc/varanda/varanda.env (referência em deploy/seeder/.env.example e deploy/seeder/compose.web.yaml) caem em três grupos. Credenciais de provedor, que podem ser as mesmas em vários servidores: VARANDA_DIDIT_API_KEY, VARANDA_DIDIT_WORKFLOW_ID, VARANDA_GOOGLE_CLIENT_ID, VARANDA_GOOGLE_CLIENT_SECRET, VARANDA_GIF_API_URL, VARANDA_GIF_API_KEY, VARANDA_GIF_MEDIA_HOSTS e VARANDA_AUDIUS_API_KEY. Chaves de dados de cada servidor, que nunca se compartilham, porque cifram os dados daquele servidor: VARANDA_PHONE_KEY e VARANDA_PAGE_KEYS. Tokens por servidor: VARANDA_TRIAGE_TOKEN e VARANDA_PUSH_TOKEN. Um servidor só de semeador não precisa de nenhuma credencial de provedor.

Só o primeiro grupo pode viajar, e só selado. Quem mantém o projeto sela essas credenciais para a chave pública X25519 de cada servidor, e o arquivo cifrado deploy/seeder/secrets.sealed.json entra no repositório por PR e segue dentro do pacote da imagem assinada. A cifra é X25519 efêmera por destinatário, HKDF-SHA256 e AES-256-GCM, com a lista de destinatários como dado autenticado. O arquivo também leva a assinatura de quem selou, e o servidor só o abre se ela é de uma chave da lista fixada deploy/seeder/secrets-signers.txt, que segue no mesmo pacote assinado: num diff de PR o arquivo selado é opaco, e qualquer um pode selar para as chaves públicas, então a assinatura é o que separa quem mantém o projeto de um PR qualquer. O seal só aceita os oito nomes do primeiro grupo: VARANDA_PHONE_KEY, VARANDA_PAGE_KEYS, VARANDA_TRIAGE_TOKEN e VARANDA_PUSH_TOKEN são recusados, então uma chave de dados ou um token de um servidor não há como selar.

No servidor. Na troca (run em auto, apply) e no reconfigure, o update.sh abre o secrets.sealed.json do pacote com a imagem nova, já conferida por digest, num contêiner sem rede, de sistema de arquivos só de leitura e sem capacidades (docker run --network none --read-only --cap-drop ALL), usando /etc/varanda/secrets-key.json e a lista de assinantes secrets-signers.txt do mesmo pacote. Do que esse contêiner escreve, só vai para o registro, ao lado do código de saída, a última linha do erro padrão quando ela é uma das mensagens conhecidas do CLI, sem valor nenhum (por exemplo erro: assinatura do arquivo selado inválida, um alarme: o arquivo não foi assinado por quem a lista fixa); qualquer outra linha fica de fora. Depois monta /var/lib/varanda-update/segredos/efetivo.env (root; o diretório é 0700): os bytes de varanda.env, a marca # segredos compartilhados (update.sh) e só as linhas abertas dos nomes que varanda.env deixa ausentes ou vazios. Um valor local não vazio sempre vence (vale a última atribuição do nome em varanda.env), e uma linha local vazia nunca esconde um valor compartilhado. O compose, o pré-voo e o update.sh compose leem o efetivo.env da versão em uso; o varanda.env nunca é reescrito. Um nome compartilhado escrito em varanda.env como export NOME=valor ou NOME: valor recusa a troca: escreva NOME=valor. O install de um servidor novo já grava o efetivo.env, então o update.sh compose usa os segredos compartilhados desde antes do primeiro apply. No rollback e na volta automática, o efetivo.env da versão anterior volta junto com o diretório da versão, sem abrir nada de novo. Sem secrets.sealed.json no pacote, sem chave, ou com o servidor fora da lista, nada compartilhado é aplicado e o servidor segue só com o varanda.env. Mas o timer nunca desliga sozinho o que vinha do arquivo selado (a verificação de idade da Didit, por exemplo): se a versão nova deixaria sem valor um nome que o efetivo.env em uso traz, o run não troca nada, registra os nomes (nunca os valores) e sai com 1, sem recusar o digest nem anotar intervenção; um apply explícito ou um reconfigure segue sem eles e registra os nomes.

Passos de quem opera o servidor:

  1. update.sh secrets-key (como root, /opt/varanda-release/current/update.sh) cria /etc/varanda/secrets-key.json (root, 0600) com a imagem instalada e imprime só a chave pública (64 hexadecimais), que vai para quem mantém o projeto; a secreta nunca sai do arquivo, e os registros vão para o erro padrão. Antes do install, ou enquanto não houve o primeiro apply, não há versão instalada: use update.sh secrets-key --image ghcr.io/varanda-org/varanda-seeder@sha256:<digest>, a mesma imagem do install, que é conferida (assinatura, como no install) antes de rodar e nunca baixa uma etiqueta. Com uma versão instalada, --image é recusado (saída 2). Se o arquivo já existe, o comando sai com 1 e não troca nada: para trocar a chave, apague o arquivo, rode de novo e mande a nova chave pública (quem mantém precisa selar de novo).
  2. O update.sh status mostra, só com nomes, segredos compartilhados: NOME NOME ... (ou segredos compartilhados: nenhum) e, quando o arquivo existe, chave dos segredos: /etc/varanda/secrets-key.json. Nunca um valor.
  3. Em update.log (e no journal): segredos compartilhados: N variáveis aplicadas quando o arquivo foi aberto; segredos compartilhados: este servidor não é destinatário quando a chave não está na lista (não é erro: no apply, ou quando o efetivo.env em uso não traz nomes compartilhados, a troca segue; no run, vale a regra do timer acima); segredos compartilhados: o pacote não traz secrets.sealed.json e segredos compartilhados: sem /etc/varanda/secrets-key.json (update.sh secrets-key) nos outros casos sem segredos. Uma chave com dono ou modo errado, um pacote com secrets.sealed.json sem secrets-signers.txt, qualquer falha ao abrir o arquivo, ou uma linha aberta fora do formato, com um nome fora dos oito, repetida ou com bytes fora do ASCII imprimível, recusam a troca ("nada mudou"). Antes de abrir, o update.sh lê o seq do arquivo com secrets verify --json, na mesma imagem e com o mesmo isolamento, sem a chave montada; uma conferência que falha ou não imprime exatamente a linha esperada também recusa (não foi possível conferir o arquivo selado (saída N); nada mudou, com o código de saída e, se for o caso, uma mensagem conhecida do CLI). Uma assinatura que não é da lista falha já nessa conferência, antes de abrir (não foi possível conferir o arquivo selado (saída 1: erro: o arquivo selado não foi assinado por uma chave da lista de quem sela); nada mudou).
  4. No perfil full, um servidor cujas credenciais do Google vêm só do arquivo selado precisa da chave e de uma versão que o liste antes do primeiro apply: o pré-voo confere o varanda.env primeiro sem exigir o cliente do Google e depois o efetivo.env candidato inteiro, e sem a chave ou fora da lista recusa a troca por falta de VARANDA_GOOGLE_CLIENT_ID. Crie a chave (passo 1, com --image), mande a pública e espere a versão que traz o arquivo selado para ela, ou ponha o cliente do Google no varanda.env. Com uma versão instalada, o apply também confere o ambiente com que a volta automática subiria (o efetivo.env em uso, ou o varanda.env sem ele) e recusa a troca antes de tocar em nada se ele não passa: mantenha os valores no varanda.env até instalar uma versão que os traga selados para este servidor, ou rode update.sh reconfigure se a versão instalada já os traz.
  5. /var/lib/varanda-update/segredos/seq (root, 0600) guarda o último arquivo selado aplicado numa linha <seq> <sha256> e um LF, em que o sha256 é o dos bytes do secrets.sealed.json aplicado, em 64 hexadecimais minúsculos. Ele é gravado depois que a troca passa na verificação de saúde e antes de /var/lib/varanda-update/atual. Se a gravação falha, a versão nova fica registrada em atual com uma intervenção, que segura o timer, e o update.sh sai com 1; o update.sh apply seguinte grava o piso e encerra a intervenção, sem mexer na versão anterior. Se nem a intervenção pode ser gravada, ele sai antes de atual, que continua na versão anterior. Uma volta automática ou uma versão sem segredos para este servidor não o mudam. A cada troca, a linha em vigor fica anotada em /var/lib/varanda-update/segredos/seq.anterior, junto do ambiente da versão anterior; o rollback põe o piso de volta nessa linha quando ela tem seq maior, e nunca o deixa abaixo do arquivo selado que volta a rodar. Um seq.anterior fora do formato recusa o rollback sem mudar nada: apague-o para voltar sem mexer no piso. O timer recusa um arquivo selado com seq menor (segredos compartilhados: o arquivo selado da nova versão tem seq X, menor que o último aplicado Y; nada mudou. Para aplicar mesmo assim, rode update.sh apply) e um com o mesmo seq e conteúdo diferente (segredos compartilhados: o arquivo selado da nova versão tem o mesmo seq X do último aplicado, com conteúdo diferente; nada mudou. Sele de novo com seq maior, ou rode update.sh apply), sem anotar a versão em recusadas e sem intervenção; o mesmo seq com o mesmo arquivo passa. O update.sh apply (e o reconfigure) aplica mesmo assim, registra os seqs e o arquivo aplicado vira o novo piso. Um arquivo seq que não seja exatamente essa linha recusa a troca nos dois caminhos: apague-o para aceitar o seq do próximo arquivo selado.

Passos de quem mantém o repositório:

  1. Uma vez, crie a sua chave de assinatura fora do repositório com varanda secrets signing-key --out <arquivo> e abra um PR que acrescenta a chave pública impressa a deploy/seeder/secrets-signers.txt (revisado como código).
  2. Guarde as credenciais em claro num arquivo NOME=valor (um por linha; linhas em branco e # são ignoradas; só os oito nomes; valores de 1 a 4096 caracteres ASCII imprimíveis, sem aspas simples, barra invertida, espaço nas pontas nem aspas duplas em volta) na sua máquina, nunca no repositório, e um arquivo de destinatários com uma chave pública por linha (até 64; # comenta).
  3. varanda secrets seal --file <plain.env> --recipients <destinatarios> --signing-key <arquivo> --seq <n> --out deploy/seeder/secrets.sealed.json (do repositório: node apps/cli/bin/varanda.js secrets seal ...). O --seq é um a mais que o do arquivo atual, que varanda secrets verify --file deploy/seeder/secrets.sealed.json --signers deploy/seeder/secrets-signers.txt mostra (assinatura válida: <assinante>, seq <n>, <n> servidor(es)); no primeiro arquivo, --seq 1. Selar de novo sempre aumenta o seq, mesmo quando só um valor muda: um servidor recusa um arquivo com o mesmo seq do último aplicado e outro conteúdo. A assinatura cobre o seq, e o timer de um servidor nunca aplica um seq menor que o último que ele aplicou: um arquivo mais velho, tirado do histórico do git e ainda assinado, não desfaz uma troca de credenciais. O --out nunca sobrescreve: para selar de novo, apague o arquivo antigo ou grave em outro caminho e mova. A saída diz quantos nomes e quantos servidores. Abra o PR com o arquivo selado; o próximo release o leva no pacote. Quem revisa confere o arquivo selado do PR com varanda secrets verify --file deploy/seeder/secrets.sealed.json --signers deploy/seeder/secrets-signers.txt (os testes do repositório também o conferem) e confere que o seq dele é maior que o da main (por exemplo, git show origin/main:deploy/seeder/secrets.sealed.json > /tmp/main.sealed.json e o mesmo verify com --file /tmp/main.sealed.json), e um PR que muda deploy/seeder/secrets.sealed.json só entra quando foi alguém que mantém o projeto que o selou.
  4. Incluir ou tirar um servidor é selar de novo e lançar: a lista de destinatários é a do arquivo, então um servidor novo só abre segredos de uma versão selada com a chave dele, e um servidor que sai da lista passa a receber "não é destinatário" nas versões seguintes. Tirar um servidor não revoga o que ele já abriu (ele guarda o efetivo.env, e os arquivos selados de versões antigas ainda abrem com a chave dele): troque essas credenciais de provedor nos provedores e sele os novos valores.
  5. varanda secrets open --key-file <chave> --file <selado> --signers <assinantes> --out <aberto.env> é o que o servidor roda por dentro; sai com 1 quando a assinatura não é da lista e com 3 quando a chave não está na lista; serve para conferir um arquivo selado num servidor de teste.

7. Para quem mantém o repositório (uma vez, nesta ordem; nenhum agente faz isso):

  1. Em Settings > Secrets and variables > Actions > Variables, crie VARANDA_RELEASE com o valor true. Só liga o release.yml.
  2. Depois da primeira execução do release, torne públicos os dois pacotes (varanda-seeder e varanda-web): Packages > pacote > Package settings > Change visibility > Public. Sem isso o servidor não baixa sem credencial.
  3. Confira, em cada pacote (Package settings > Manage Actions access), que o repositório tem acesso Write; sem ele o promote falha ao mover a tag. Pode não ser preciso quando o fluxo que publica está no mesmo repositório que o pacote: confira em vez de supor.
  4. Settings > Environments > New environment release-stable: revisores obrigatórios (quem mantém), sem autorrevisão e implantação só a partir de main. Faça isto ANTES de definir VARANDA_PROMOTE: o GitHub cria um ambiente que falta sem proteção nenhuma na primeira vez que um job o cita.
  5. Só então defina a variável VARANDA_PROMOTE com o valor true (liga só o promote.yml).
  6. Rode o promote (Actions > promote > Run workflow, em main, com o SHA de 40 dígitos de um commit já publicado pelo release) para a primeira versão stable.
  7. Rode a lista de docs/verification/feat-seeder-pull-updater.md num servidor de teste antes de migrar a produção.

systemd

deploy/seeder/varanda-seeder.service roda seed --json como o usuário de sistema varanda, com os dados em /var/lib/varanda/seeder e o endpoint de saúde em 127.0.0.1:8788. Reinicia 5 s depois de uma falha (código 1), mas não depois de um erro de uso (código 2, configuração errada). Para com SIGTERM e espera até 30 s. Instalação, como root (Node 20 ou mais novo em /usr/bin/node; ajuste o ExecStart se não for o caso):

useradd --system --home-dir /var/lib/varanda --shell /usr/sbin/nologin varanda
git clone https://github.com/Varanda-org/varanda.git /opt/varanda
cd /opt/varanda && npm ci --omit=dev --workspace apps/cli --ignore-scripts
install -d -o varanda -g varanda -m 0700 /var/lib/varanda
install -m 0644 deploy/seeder/varanda-seeder.service /etc/systemd/system/
install -D -m 0600 deploy/seeder/seeder.env.example /etc/varanda/seeder.env

Chave e certificado, como o usuário varanda (o arquivo do certificado precisa ser legível por ele):

sudo -u varanda env VARANDA_DATA=/var/lib/varanda/seeder node /opt/varanda/bin/varanda.js seed key --association "$ASSOC"
sudo -u varanda env VARANDA_DATA=/var/lib/varanda/seeder node /opt/varanda/bin/varanda.js seed cert add --cert-file /caminho/seeder-cert.json

Subir e ver a saúde:

systemctl daemon-reload
systemctl enable --now varanda-seeder
curl -s http://127.0.0.1:8788/health

Registros: journalctl -u varanda-seeder -f. seed list e seed drop: systemctl stop varanda-seeder, o comando como o usuário varanda (como acima), systemctl start varanda-seeder.

Política de registros

Provisória até o parecer jurídico sobre registros de acesso (issue #38).

  • Formato. Uma linha por evento na saída padrão. No serviço, --json: JSON Lines com os eventos health, ws, ready, peer, admitted, rejected, have, peer-dropped, warning, fatal e stopped (o mais frequente é have, a cada crescimento de um diário). Erros vão para a saída de erro como erro: <mensagem>. A linha não traz data e hora (o journal e o Docker carimbam cada uma), exceto o instante at de ws e ready e o stopListeningAt de stopped, em ms desde 1970, que medem uma implantação.
  • O que entra. Chaves públicas de diários (64 hex), com tamanho ou motivo de recusa; a chave Noise dos pares (peer, peer-dropped); o tópico da associação (ready). São pseudônimos, e contam como dado pessoal quando alguém consegue ligá-los a uma pessoa.
  • O que nunca entra. Endereço IP ou porta de par (a entrada WebSocket nunca registra o endereço do cliente), conteúdo de publicação ou de perfil, certificados, chaves secretas e as requisições ao endpoint de saúde.
  • Estatísticas de uso (serviço de conta). O serviço de conta acrescenta só { event: 'usage', reason }, com reason igual a ligada, desligada, invalido ou falhou. A linha não traz e-mail, chave, @nome nem endereço.
  • Rotação. Pelo supervisor. Docker: driver json-file com até 5 arquivos de 10 MB (compose.yaml). systemd: o journal rotaciona sozinho.
  • Retenção provisória: 30 dias. No systemd, deploy/seeder/journald-varanda.conf vai para /etc/systemd/journald.conf.d/varanda.conf (MaxRetentionSec=30day). Vale para o journal inteiro da máquina, então use numa máquina dedicada. No Docker o limite é de volume (50 MB), não de tempo; para limitar por tempo, troque o driver para journald no compose.yaml e use a mesma configuração.
  • Registros de acesso (Marco Civil, Art. 15). O semeador não registra endereço IP, então hoje não guarda registro de acesso. Se o parecer concluir que o Art. 15 se aplica à associação, a guarda por 6 meses vai exigir registrar endereço e horário das conexões (mudança de código, ainda não feita) e ajustar a retenção acima. A retenção é configuração do supervisor (MaxRetentionSec, max-size e max-file), não do código: muda sem nova versão.

Bloquear uma conta

A associação mantém uma lista de bloqueio assinada pela chave da moderação. Cada nó (semeador, membro de linha de comando e versão web) troca a lista com os pares no canal varanda/blocklist/1, guarda a mais nova que confere e deixa de guardar, servir e mostrar os diários bloqueados. A lista traz só chaves públicas (contas bloqueadas e emissores revogados), um número de sequência e a data: nunca o motivo, um nome ou um e-mail.

Tudo roda na máquina do operador, num diretório só da moderação (--data <modDir>, separado do da associação, de membro, de semeador e do serviço de conta). A chave secreta da moderação nunca vai para o servidor: só a lista assinada sai da máquina.

  1. Crie a chave da moderação e grave a chave pública Noise do semeador da associação (seed status a mostra); o comando imprime só a chave pública da moderação e nunca troca uma chave existente:

    node bin/varanda.js mod init --data <modDir> --association <hex> --seeder <chave do semeador>

    --seeder é opcional aqui: rodar mod init --seeder <chave> de novo num diretório que já existe só grava ou troca a chave do semeador. Sem ela gravada, cada comando que publica precisa de --seeder <chave>; sem nenhuma das duas, o comando sai com erro: informe --seeder <chave do semeador> (seed status a mostra) ou use --no-publish (código 1) antes de assinar qualquer coisa.

  2. Com a associação, certifique essa chave e grave o certificado na moderação:

    node bin/varanda.js assoc certify-moderator --data <assocDir> --moderator <hex> --out moderator-cert.json
    node bin/varanda.js mod cert add --data <modDir> --cert-file moderator-cert.json
  3. Bloqueie ou desbloqueie uma conta pela chave pública do diário (64 hex). A primeira lista da associação precisa de --new-list:

    node bin/varanda.js mod block <chave> --data <modDir> --new-list
    node bin/varanda.js mod block <outra chave> --data <modDir>
    node bin/varanda.js mod unblock <chave> --data <modDir>

Cada comando grava a próxima lista (seq + 1) em blocklist.json, anota a mudança em moderation.jsonl e publica a lista (as mesmas opções --bootstrap e --dht-host de sync). Num diretório sem blocklist.json, um comando que muda a lista recusa sem --new-list (erro: este diretório não tem lista anterior; ..., código 1, nada assinado): uma lista começada do zero por engano desfaria, em todos os nós, todos os bloqueios e revogações anteriores. Com uma lista já gravada, --new-list é recusado (erro: este diretório já tem uma lista).

A lista vai só para o semeador da associação: o publicador o chama direto pela chave Noise dele, com uma chave Noise descartável (nunca a da moderação nem a da associação), sem entrar no tópico público da associação. A entrega só conta quando esse par se prova semeador da associação (o hello traz um certificado de semeador da associação para a chave Noise da própria conexão) e responde que guardou exatamente essa lista (o have dele traz o início da assinatura da lista): lista publicada, código 0. Se o semeador já tem outra lista com o mesmo número (acontece ao restaurar uma cópia antiga do diretório da moderação), o comando sai na hora com erro: o semeador já tem outra lista com o mesmo número (seq N); isto acontece ao restaurar uma cópia antiga da moderação e faça uma nova alteração (ela recebe um número maior) ou rode mod publish depois de recuperar a lista mais recente (código 1). De lá os nós a repassam entre si. O semeador precisa estar no ar. Sem confirmação em --timeout-ms (padrão 30000), o comando sai com erro: não foi possível publicar a lista e a lista ficou gravada; rode mod publish quando o semeador estiver no ar (código 1). mod publish reenvia a lista gravada sem mudar nada (mesmo seq, nenhuma linha nova em moderation.jsonl); sem lista gravada, erro: nenhuma lista para publicar. --no-publish só grava. Desbloquear uma chave que não estava na lista também gera uma lista nova e diz não estava bloqueada.

Quem vê o endereço IP da máquina do operador ao publicar: o semeador (infraestrutura da associação) e os nós da DHT que encaminham a busca e a conexão até a chave dele. Os pares do tópico da associação não veem.

mod show mostra a associação, a chave pública da moderação, o estado do certificado e a lista (lista seq <n> de <data>: <k> contas bloqueadas, <r> emissores revogados, ou lista vazia). Com --json, os comandos imprimem a lista pública; nenhum imprime a chave secreta.

Se a chave do emissor do serviço de conta vazar, mod revoke-issuer <chave> põe essa chave na lista de emissores revogados: os certificados de membro v2 e os @nomes que ela assinou deixam de valer em todos os nós. mod unrevoke-issuer <chave> desfaz. As duas publicam a lista como block.

Uma chave da moderação nova (outro mod init em outro diretório, certificada depois da atual) substitui a anterior: os nós aceitam a lista dela como mais nova mesmo começando de seq 1. Para trocar a chave sem perder nada, copie o blocklist.json da moderação anterior para o diretório novo antes do primeiro comando: o código continua dessa lista (mantém todos os bloqueios e emissores revogados) e assina a próxima com a chave nova. Sem a cópia, o diretório novo recusa sem --new-list, que só serve para a primeira lista da associação.

Ligar o painel de moderação e as denúncias (serviço account)

As denúncias dos membros e o painel dos moderadores rodam no mesmo serviço account. As denúncias não pedem configuração nova (só quem tem a conta vinculada pode denunciar, pela versão web hospedada); o painel só liga se houver moderadores configurados:

  1. No cliente OAuth do Google Cloud, mantenha https://<domínio>/account/mod/callback em "URIs de redirecionamento autorizados". O URI https://<domínio>/account/callback foi retirado para membros e pode continuar registrado enquanto houver versões antigas do app. VARANDA_GOOGLE_CLIENT_ID e VARANDA_GOOGLE_CLIENT_SECRET continuam obrigatórios, usados só pelo painel.
  2. Em deploy/seeder/.env, ponha em VARANDA_MODERATOR_EMAILS os e-mails Google dos moderadores, separados por vírgula, em minúsculas (no máximo 32). Só esses e-mails entram no painel; vazio mantém o painel desligado e o vínculo e as denúncias seguem funcionando. O deploy.sh confere o formato sem imprimir os valores.
  3. O contêiner lê o .env só ao ser criado: depois de editar a lista, recrie o serviço (docker compose -f deploy/seeder/compose.yaml -f deploy/seeder/compose.web.yaml up -d --force-recreate account). Reiniciar não basta.
  4. O painel fica em https://<domínio>/account/mod/. A sessão do moderador é guardada só na memória do serviço (8 horas): reiniciar ou recriar o contêiner desconecta todos, e basta entrar de novo.

Os moderadores marcam cada denúncia como bloquear ou descartar, e desbloqueiam em "Bloqueadas". Descartar vale na hora e não muda a lista; bloquear e desbloquear só viram lista depois do mod apply abaixo. O painel mostra chaves e @nomes, nunca e-mails; um moderador não vê, decide nem desbloqueia nada sobre a própria conta vinculada. O arquivo moderation.json (denúncias, decisões e mudanças pendentes, modo 0600) fica no volume account-data, junto do diretório de contas: inclua-o no backup do volume.

Recurso de quem foi bloqueado. Quem tem a conta vinculada e a chave bloqueada (na lista publicada ou com bloqueio pendente) abre, na versão web hospedada ou no app com a instalação, Ajustes › Recorrer de um bloqueio, escreve até 1000 caracteres (opcional) e envia. O pedido é assinado com a chave do diário (appeal.sign) e vai ao serviço de conta (POST /account/appeal/start e POST /account/appeal); fica só em moderation.json (campo appeals), nunca no diário nem na lista. Cada bloqueio tem um recurso; negado, a chave só recorre de novo em 30 dias. Quando a chave deixa de estar bloqueada (desbloqueio, bloqueio cancelado, lista publicada sem ela), o recurso aberto é encerrado (encerrado) e um bloqueio novo começa sem ele. No painel, a aba "Recursos" lista os abertos para quem não decidiu o bloqueio daquela chave (o painel compara o e-mail de quem decidiu a denúncia; um bloqueio feito fora do painel, por mod block, ou pela IA, não exclui ninguém) e nunca para a própria pessoa recorrente. "Aceitar" pede o desbloqueio, que aparece em "Pendentes" e só sai da lista no próximo mod apply com confirmação no terminal (um desbloqueio nunca sai com --yes); "Negar" só encerra o caso, com a nota. Com um único moderador configurado, o recurso de um bloqueio dele fica sem quem decida: o operador usa "Desbloquear" em "Bloqueadas". account reports ainda não exporta os recursos.

Para um pedido legal, account reports [--member <chave>] (rodado no servidor, como account status, por exemplo docker compose ... run --rm account account reports --member <hex>) imprime uma linha JSON por denúncia, com reporterContact e targetContact ({ email, username } ou null). É o único caminho pelo qual o e-mail do vínculo sai do serviço: não rode em outra máquina nem cole a saída em chamados, e não está nos registros. Sem --member lista todas; com ele, as feitas contra aquela chave.

Estatísticas de uso (opcional)

A aba "Estatísticas" do painel mostra só contagens anônimas. Sem VARANDA_STATS_EMAILS ela fica desligada, junto com a amostragem e o usage.json.

  • VARANDA_STATS_EMAILS: e-mails Google de quem pode ver a aba, separados por vírgula, em minúsculas (no máximo 32). É um subconjunto de VARANDA_MODERATOR_EMAILS: cada endereço precisa estar também na lista de moderadores. Vazio ou ausente desliga a aba. O deploy.sh e o serviço conferem o formato e o subconjunto sem imprimir os valores. O contêiner lê o .env só ao ser criado: depois de editar, recrie o serviço account, como no passo 3. Reiniciar não basta.
  • VARANDA_SEEDER_HEALTH: de onde o serviço lê o GET /health do semeador. O padrão é http://127.0.0.1:8788. Só HTTP em loopback (127.0.0.1, localhost ou [::1]), com porta explícita. Só é lido quando as estatísticas estão ligadas.

A aba mostra os membros vinculados e o teto, os diários no semeador, os ativos hoje e nos últimos 7 dias (dia de Brasília, UTC−3), as conexões, as publicações indexadas, o armazenamento, os cadastros por semana (12) e por mês (12, cada mês com o total acumulado) a partir de linkedAt, e uma tabela dos últimos 30 dias. Não mostra contagem de denúncias. Se o semeador reiniciou há menos de 7 dias, a aba avisa que os ativos ainda estão parciais ("O semeador reiniciou há menos de 7 dias: os ativos ainda estão parciais.") e eles recomeçam em 0.

O histórico fica em usage.json, no volume account-data. Uma linha por dia de Brasília (UTC−3), no máximo 400, modo 0600. Um arquivo inválido nunca é regravado: o painel avisa "Histórico indisponível (usage.json inválido): avise a operação." e a operação pode olhar o arquivo. Apagá-lo só perde o histórico.

A amostragem grava a cada 15 minutos (a primeira cerca de um minuto depois de subir) e, com a aba aberta, faz no máximo uma leitura ao vivo a cada 5 minutos. Os ativos (activeDay, activeWeek) e as conexões (connections, external) guardam o pico do dia; os totais (membros, diários, blocos, bytes, mídia e publicações indexadas) guardam o valor mais recente. Uma leitura que falta não apaga o que já estava na linha.

Privacidade: só contagens, sem chave, e-mail ou @nome. A data de cadastro já aparece no certificado público de cada membro (linkedAt é a data desse certificado), então as células de cadastro não são suprimidas. Os dias dos cadastros por semana e por mês são o dia de Brasília (UTC−3).

Triagem com IA (opcional)

A triagem lê a publicação denunciada no semeador e compara com decisões humanas já tomadas. Comece em sombra e só passe a 1 quando as sugestões coincidirem com o que os moderadores decidem.

No deploy/seeder/.env (o contêiner só lê o arquivo ao ser criado: depois de gravar estas linhas, recrie account e o seeder, como no passo 3):

  • VARANDA_AI: vazio ou ausente desliga (padrão). sombra só registra o que a IA faria e mostra a sugestão no painel. 1 deixa a IA decidir. Outro valor é erro de uso antes de abrir a porta. Sem o modelo o serviço sobe sem triagem (sem-modelo) e a checagem de saúde continua verde.
  • VARANDA_TRIAGE_TOKEN: 64 hex minúsculos, o mesmo valor no semeador e no serviço de conta (openssl rand -hex 32). Sem ele as rotas de leitura (/moderation-post/ e /moderation-group-post/) não existem no semeador; com VARANDA_AI ligado e o token vazio ou inválido, o serviço de conta recusa subir (erro de uso), e no Compose o contêiner fica reiniciando. Um token malformado é erro de partida mesmo com a IA desligada. Para bloquear uma denúncia de grupo (conta ou grupo) o serviço de conta lê a mensagem em /moderation-group-post/ e confere grupo e diário; sem o token os dois bloqueios de uma denúncia de grupo são recusados, mesmo com a IA desligada, e o painel mostra o texto conferido ("Texto conferido no semeador:"). Defina o mesmo token nos dois serviços para moderar grupos. Com o token configurado, o serviço de conta também o envia nas leituras /index/group e /index/groups do semeador, que as cobra do orçamento de moderação e não do balde público do índice (a resposta é a mesma; token ausente ou errado cai no balde público).
  • VARANDA_SEEDER_HTTP: onde a conta alcança o HTTP do semeador. Padrão http://127.0.0.1:8789. É lido e validado mesmo com a triagem desligada: o painel só decide Bloquear grupo depois de confirmar o grupo, o escritor e a existência da mensagem (o comprimento do escritor passa da posição; senão sem-mensagem) na rota pública /index/group/<chave> desse endereço (no máximo 8 páginas, 5 s, sem nova tentativa). Numa denúncia de grupo, tanto Bloquear conta quanto Bloquear grupo exigem essa confirmação; qualquer falha, inclusive um semeador fora do ar ou não configurado, recusa a decisão (grupo-nao-confirmado). Sem um semeador alcançável, uma denúncia de grupo só pode ser descartada (Descartar sempre funciona). O mesmo vale para toda denúncia sem grupo, com ou sem conta vinculada no alvo: Bloquear exige que o semeador confirme um diário servido (GET /index/groups/<chave> responde 200; senão alvo-nao-confirmado). Sem um semeador alcançável, nenhuma conta pode ser bloqueada pelo painel: todas as denúncias só podem ser descartadas.
  • VARANDA_AI_MODEL_DIR: diretório dos pesos, só fora do Compose. Padrão <dataDir>/ai-model. No Compose ele é fixo em /data/ai-model, dentro do volume account-data: não o defina no .env.

Baixe os pesos uma vez. O script confere o sha256 dos cinco arquivos e recusa um diretório dentro do repositório. No Compose, grave direto no volume do serviço de conta, com a própria imagem:

docker compose -f deploy/seeder/compose.yaml -f deploy/seeder/compose.web.yaml run --rm --entrypoint node account apps/cli/scripts/fetch-ai-model.js --dir /data/ai-model

Fora do Compose:

node apps/cli/scripts/fetch-ai-model.js --dir <dataDir>/ai-model

Numa instalação local, prefira npm ci --ignore-scripts (ou defina ONNXRUNTIME_NODE_INSTALL_CUDA=skip, que evita o download de artefatos CUDA no linux x64). O CI, o fluxo de deploy, deploy/seeder/build-web.sh e a imagem Docker instalam com --ignore-scripts: nenhum script de instalação de dependência roda, e os binários nativos usados já vêm nos pacotes.

No Histórico do painel, uma decisão da IA tem o botão Reabrir: a denúncia volta para Abertas e uma pessoa decide; a reabertura fica gravada na própria denúncia (campo reopened em moderation.json) e a IA nunca a decide de novo. Reabrir não desfaz nada: um bloqueio da IA continua até alguém usar Desbloquear (ou cancelar, enquanto está em Pendentes). O pull de moderação não muda. As marcas da triagem ficam em triage-marks.jsonl, uma linha por marca nova (uma marca igual não grava nada), compactado de tempos em tempos em triage.json.

account status mostra Triagem IA: desligada, Triagem IA: <n> precedentes ou Triagem IA: indisponível (exemplars.json inválido). Inclua exemplars.json, triage.json e triage-marks.jsonl no backup do volume account-data, junto de moderation.json (modo 0600).

Avisos push (opcional)

Avisos do sistema na versão web hospedada, para quem ligar em Ajustes ("Avisos no aparelho"). São seis eventos de membros: alguém começou a seguir, respondeu, citou, mencionou, curtiu ou republicou. O crescimento de um diário seguido não entra aqui. A lista de Avisos do app continua sem usar este caminho.

Outro aviso nasce no próprio serviço de conta, não no semeador: com VARANDA_INVITE_DROPS=1, chega um aviso quando um convite abre. O título é "Chegou um convite pra sua varanda" e o texto, "Escolha com carinho quem você quer chamar: alguém próximo, que faz falta na conversa." O payload { v: 1, kind: 'invite-drop' } não nomeia ninguém e não leva texto: título e texto ficam fixos no service worker (tag varanda-invite-drop), e tocar no aviso abre Ajustes › Convidar pessoas (/?aviso=convite). Só a PWA hospedada recebe; o app nativo vê o convite dentro do app, sem push. Só vai para quem aceitou Termos e Política na versão 16, para todos os aparelhos do membro ou para nenhum, e o TTL fica limitado ao fim da janela do dia (21:00 de Brasília): um aviso que não saiu até lá é descartado. Os avisos de convite ocupam no máximo um quarto da fila de envio e só entram enquanto ela está com menos da metade cheia.

O serviço de conta precisa estar parado na primeira vez. No diretório de dados da conta:

node bin/varanda.js account push-key --data <dataDir>

O comando grava push-vapid.json (modo 0600, { v: 1, publicKey, privateKey }) no volume account-data e imprime só a chave pública (chave pública de push: ...). Recusa com serviço de conta em execução se o lock está preso, e com chave de push já existe se o arquivo já está lá. Para girar a chave: apague push-vapid.json com o serviço parado, rode account push-key outra vez e peça que cada pessoa ligue os avisos de novo neste navegador. A chave nova deixa as inscrições antigas órfãs.

No deploy/seeder/.env (o contêiner só lê o arquivo ao ser criado; depois de gravar, recrie o semeador e o serviço account):

  • VARANDA_PUSH_TOKEN: 64 hex minúsculos, o mesmo valor no semeador e no serviço de conta. Gere com openssl rand -hex 32. Vazio ou ausente desliga: o semeador não faz o repasse e POST /push-event responde 404.
  • VARANDA_ACCOUNT_HTTP: onde o semeador alcança o HTTP do serviço de conta. Padrão http://127.0.0.1:8790. Só HTTP em loopback (127.0.0.1, localhost ou [::1]), com porta explícita.

O que fica guardado: push-vapid.json (o par VAPID) e push.json (a inscrição de cada aparelho: endpoint, p256dh, auth e createdAt), os dois modo 0600 no volume account-data. No máximo 4 aparelhos por membro. account export soma pushDevices e nunca o endereço. account status mostra avisos push: ligados (N aparelhos), avisos push: desligados ou avisos push: indisponível (push.json inválido).

Nada de inscrição, chave, nome ou texto do aviso entra no registro. As linhas são só { event: 'push', reason }.

O endpoint tem de ser uma URL https canônica, em ASCII imprimível. isEndpoint (packages/core/lib/push-proof.js) exige https, de 1 a 2048 caracteres, ASCII imprimível, sem barra invertida, sem # e sem usuário na autoridade. isPushEndpoint (packages/rpc/lib/methods.js, no push.sign) e endpointParam (POST /account/push/finish e POST /account/push/check) exigem o mesmo e ainda new URL(valor).href === valor: porta 443 explícita, host em maiúsculas e segmentos . ou .. não entram.

O semeador nunca vê a inscrição. Ele só manda o candidato em loopback (POST /push-event, Authorization: Bearer com VARANDA_PUSH_TOKEN). O Caddy não encaminha essa rota (apps/cli/test/caddyfile.test.js). O serviço compara o sha256 do token com timingSafeEqual. Sem o token, a rota não existe (404) e o corpo não é lido.

Um aviso que chega com o serviço de conta fora, ou com a fila do repasse cheia (256 no semeador, 512 no serviço), se perde e não é repetido. Um bloco escrito enquanto o semeador estava fora só vira aviso depois que ele volta se o at do autor tiver menos de 24 h (PUSH_MAX_AGE_MS, só para suprimir). O que já estava guardado quando o diário passou a ser servido não gera aviso, inclusive depois de reiniciar ou de reconstruir o índice.

Estado de vistos entre aparelhos

O serviço de conta guarda em seen/<membro> (diretório 0700, arquivos 0600, no volume account-data) um bloco cifrado de 32808 bytes por membro, com as marcações de visto mais recentes de Avisos, Conversas e grupos. Só os aparelhos da passkey abrem o bloco (docs/protocol.md, seção 14); o serviço vê só que ele existe, o tamanho fixo e a hora da última gravação. Não há variável para ligar: POST /account/seen/start e POST /account/seen/finish ficam sempre montadas, e gravar exige o aceite dos Termos atuais. O backup leva o diretório com o resto do volume. Perder o diretório não perde nada para sempre: cada aparelho guarda as próprias marcações e as grava de novo no passe seguinte. Um seen que não é um diretório (um link simbólico, um arquivo) deixa o recurso indisponível até ser corrigido, com uma linha { event: 'seen', reason: 'diretorio-invalido' } no registro; nenhum membro, hash ou byte do bloco entra no registro.

Aplicar as decisões do painel

Os moderadores decidem as denúncias no painel do serviço de conta (/account/mod/), mas o painel não assina nada: cada decisão fica pendente até o operador rodar mod apply na própria máquina, com o diretório da moderação. A chave secreta da moderação continua só nessa máquina.

node bin/varanda.js mod apply --server https://<domínio> --data <modDir>

--server é a origem pública do serviço (https://<domínio>, sem caminho nem barra no fim; http:// só vale para 127.0.0.1, nos testes; outra coisa é uso: server inválido, código 2). O comando faz dois pedidos assinados pela chave da moderação, cada um com um desafio de uso único do servidor e presos a essa origem (uma assinatura para um domínio não vale em outro):

  1. busca as decisões pendentes (api/pull) e a última lista que o painel confirmou;
  2. confere a lista local: se blocklist.json está atrás da publicada, sai com erro: lista local atrás da publicada; restaure o backup da moderação (código 1) sem gravar nada;
  3. aplica as decisões na ordem em que foram tomadas e mostra, antes de assinar, uma linha por chave com o efeito final: bloquear <chave>, desbloquear <chave>, já estava bloqueada <chave> ou não estava bloqueada <chave>. Um desbloqueio de chave cujo bloqueio não veio do painel (feito com mod block, ou sem registro em moderation.jsonl) aparece como desbloquear <chave> (bloqueada pela operação). Um bloqueio pedido só pela IA aparece como bloquear <chave> (ia); com --yes ele não é assinado e aparece como bloquear <chave> (ia) — aguarda revisão no terminal, até um mod apply num terminal. Um bloqueio pedido pela própria pessoa ao excluir a conta (seção "Excluir conta", abaixo) aparece como bloquear <chave> (exclusão pedida pela pessoa) e o --yes o assina como um bloqueio pedido por pessoa. Bloqueios da IA e exclusões chegam pelo mesmo caminho; o programa do operador tem de ser atualizado junto com o servidor, porque um mod apply anterior recusa a resposta nova do pull, { changes: [{ id, op, member, at, actor }], published: { snapshot } } (actor é ia, titular ou pessoa);
  4. pede a revisão (abaixo), assina UMA lista nova (seq + 1, uma linha por chave em moderation.jsonl) e a publica no semeador como mod block;
  5. só com a lista entregue, confirma ao painel (api/ack) as decisões aplicadas e a lista assinada: aplicado: seq <n>, <k> chaves bloqueadas.

Nada que o servidor devolve é assinado sem revisão. Num terminal, o comando pergunta Assinar e publicar estas mudanças? [s/N] e só segue com s ou sim; outra resposta sai com erro: nada assinado (código 1), sem assinar, publicar nem confirmar nada. Se houver desbloqueios de chaves bloqueadas pela operação, pergunta de novo, Desbloquear também as chaves bloqueadas pela operação? [s/N] ; recusando, só essas chaves ficam de fora e seguem pendentes no painel. Sem terminal (cron, pipe) e sem --yes, sai com erro: rode num terminal para revisar, ou use --yes para aplicar só os bloqueios (código 1) antes de qualquer pedido ao servidor.

--yes é para o agendamento: aplica só os bloqueios pedidos por pessoas (os da IA e os desbloqueios ficam para a revisão no terminal), no máximo 100 chaves novas por execução (mais que isso sai com erro: muitos bloqueios de uma vez; rode no terminal para revisar, código 1, nada assinado). Toda chave cujo efeito final é um desbloqueio fica retida: nenhuma decisão dela é assinada nem confirmada, e a saída diz desbloqueios aguardando revisão no terminal: <n>. As decisões retidas continuam pendentes no painel até a próxima execução num terminal, que as mostra e pede a confirmação. Assim, quem roubar o login Google de um moderador (ou controlar o servidor de conta) pode enfileirar decisões e fazer o cron bloquear até 100 chaves por execução, mas não desbloqueia ninguém sem o operador revisar no terminal; nenhum dos dois publica nada sem a chave da moderação, que fica na máquina do operador.

Se a publicação falhar (erro: não foi possível publicar a lista, código 1), nada é confirmado e a lista nova fica gravada; a próxima execução reenvia exatamente a mesma lista antes de confirmar (confirmado: seq <n>). Sem decisões pendentes e com a lista já confirmada, imprime nada a aplicar. Se o painel já confirmou uma lista mais nova, sai com erro: o servidor tem uma lista mais nova; restaure o backup. Uma resposta fora do formato esperado é erro: resposta inválida do servidor. Num diretório sem blocklist.json, aplicar decisões exige --new-list, como em mod block. --no-publish é recusado (código 2); --json imprime na última linha a lista pública, os identificadores das decisões confirmadas e quantos desbloqueios ficaram retidos (held); nenhuma saída traz a chave secreta, e-mail ou endereço de par.

O "Pendentes" do painel só esvazia depois de um mod apply bem-sucedido, então rode-o com --yes num agendamento (por exemplo, a cada hora pelo cron) na máquina do operador, e rode-o num terminal, sem --yes, para revisar e aplicar os desbloqueios e os bloqueios da IA retidos. Depois do primeiro deploy do painel, rode-o uma vez sem nenhuma decisão: ele confirma a lista que mod block já tinha publicado, e "Bloqueadas" passa a mostrar a mesma lista. Se o diretório da moderação ainda não tem lista (nenhum mod block antes), a primeira execução é node bin/varanda.js mod apply --server https://<domínio> --data <modDir> --new-list; depois disso, nunca mais com --new-list. Faça uma cópia do diretório da moderação (blocklist.json, moderation.jsonl, a chave e o certificado) antes de cada execução: é dela que vem o blocklist.json para "restaurar o backup". mod apply segura o mesmo bloqueio do diretório que os outros comandos mod (erro: outra operação de moderação em andamento).

Excluir conta

A pessoa exclui a conta no app, em Ajustes > Excluir conta (a diretriz 5.1.1(v) da App Store exige que a exclusão comece no app). Ela digita o @nome, confirma com a passkey, e o app manda o pedido assinado ao serviço de conta (POST /account/delete/start e /account/delete/finish, detalhes em docs/protocol.md, "Account deletion"). As rotas existem sempre, mas sem o painel de moderação ligado o pedido é recusado (indisponivel), porque o diário só sai da rede pela lista assinada, e sem um passkeys.json utilizável também.

O serviço confere a confirmação com a passkey: logo depois do vínculo da conta, o app manda a chave pública da passkey que criou a conta (POST /account/passkey/start e /account/passkey/add, aceito só na primeira hora depois do vínculo e só se a conta ainda não tem chave), e o serviço a guarda em passkeys.json. No pedido, ele confere a assinatura da passkey sobre o nonce, a origem, o rpId (o host de VARANDA_PUBLIC_ORIGIN) e a verificação do usuário antes de excluir. A origem do app Android vem de VARANDA_ANDROID_CERT_SHA256 (o mesmo valor do assetlinks.json, abaixo, passado também ao serviço account); sem ela, uma exclusão pelo app Android cai na espera. Sem chave guardada (toda conta vinculada antes disso, uma criação no iOS sem objeto de atestado, ou outra passkey), a exclusão fica agendada por 7 dias: GET /account/status passa a ter scheduledDeletion, todos os aparelhos mostram o pedido, chega um aviso push se ligado, e qualquer aparelho cancela (/account/delete/cancel/start e /finish). A varredura de hora em hora executa as exclusões agendadas que venceram.

Na exclusão, o serviço:

  1. enfileira no painel o bloqueio da chave, marcado como pedido pela própria pessoa, mesmo quando já havia um bloqueio pendente de moderador ou da IA para ela: o painel não deixa cancelar nenhuma mudança dessa chave nem desbloqueá-la (conta-excluida), e o --yes assina; só um mod unblock do operador, no terminal, desfaz;
  2. apaga do diretório o vínculo (sub, e-mail, certificado, registros e o convite usado) e guarda só a chave pública, a data e os @nomes que a conta usou, que ficam queimados. No serviço de conta, o número do celular fica lacrado no phone.json por até 180 dias e então é apagado, como na versão 36 dos Termos. A mesma chave não volta a se vincular; sem bloqueio, o número fica livre para uma conta nova com outra passkey;
  3. apaga terms.json, age.json, push.json, recovery.json (fica a marca de remoção de 30 dias, com a chave pública), os convites que a pessoa criou, as marcas de invite-drops.json, o bloco cifrado de vistos (seen/<chave>) e a chave da passkey com o agendamento em passkeys.json (também com marca de 30 dias). Uma varredura repete isso na partida e a cada hora, para o que não pôde ser apagado na hora; o registro tem só { event: 'exclusao', reason } e contagens, nunca a chave.

Ficam as denúncias e as decisões dos moderadores (moderation.json, retenção em aberto na issue #38). Quem ainda é dono de uma página recebe paginas-ativas e precisa encerrá-la ou transferi-la antes.

O app promete que o diário sai dos semeadores em até 7 dias, então rode mod apply --yes agendado (a cada hora, como na seção anterior): ele assina as exclusões sem esperar o terminal. GET /account/status?member=<chave> responde { "linked": false, "deleted": "pendente" } até a lista com a chave chegar ao semeador e o painel confirmá-la, e "concluida" depois; o app usa isso para avisar a pessoa. Cada exclusão ocupa uma das 4096 vagas da lista de bloqueio (MAX_BLOCKED).

A primeira exclusão grava deleted no directory.json: voltar a uma versão anterior a esta precisa do backup de antes dela, como na primeira página.

Servidor local para a interface web (varanda-serve)

node bin/varanda-serve.js roda um nó Varanda (a sessão do núcleo) neste computador e o expõe a uma interface no navegador por um WebSocket local. As chaves ficam nesta máquina. É um programa separado: node bin/varanda.js não muda.

node bin/varanda-serve.js --data ./data --association <hex> \
  --bootstrap 127.0.0.1:49737 --dht-host 127.0.0.1 --ui apps/app/dist

Imprime uma vez, depois de começar a escutar:

varanda-serve em http://127.0.0.1:<porta>
abra http://127.0.0.1:<porta>/#token=<token>

Sem --ui, a segunda linha é token: <token>. O token só aparece nessa linha. Na URL ele vai depois do #, que o navegador não envia ao servidor.

Opções (--help imprime a lista):

  • --port <n>: porta local, padrão 8787. 0 escolhe uma porta livre.
  • --origin <url>: origem permitida no WebSocket, repetível, escrita exatamente como o navegador a envia (http://localhost:8081, sem barra no fim).
  • --ui <dir>: diretório com a exportação web estática. Com ele, http://127.0.0.1:<porta> e http://localhost:<porta> também são origens permitidas.
  • --public-dht: usa a DHT pública. Aqui ela é opt-in: sem --bootstrap (ou VARANDA_BOOTSTRAP) e sem --public-dht o servidor recusa com uso: informe --bootstrap ou --public-dht. As duas juntas também são erro de uso. Com --public-dht, um --dht-host de loopback (127.x.x.x, localhost, ::1) é recusado com uso: dht-host de loopback e DHT pública são exclusivos.
  • --data, --association, --bootstrap, --dht-host e as variáveis VARANDA_* funcionam como no varanda. Sem --association, vale a associação do config.json de membro já existente.

O token são 32 bytes aleatórios (64 dígitos hexadecimais), gerados a cada início. Não existe opção --token (a linha de comando é visível a todo usuário local em ps) nem token fixo: VARANDA_SERVE_TOKEN é recusado (uso: VARANDA_SERVE_TOKEN não é aceito: o token é gerado a cada início). O endereço impresso é uma credencial enquanto o processo roda: a página tira o token da barra de endereço, mas o navegador pode guardar a visita no histórico. Prefira abrir o endereço numa janela anônima e encerre o varanda-serve quando terminar; ao reiniciar, abra o endereço novo.

Recusas antes de escutar (código 2, uso: <mensagem>): diretório de semeador ou de associação (uso: diretório não é de um membro), chave ou bootstrap inválidos, nenhuma origem permitida (uso: informe --origin ou --ui), opção desconhecida. Porta ocupada: erro: porta em uso, código 1.

Regras de segurança:

  • Escuta só em 127.0.0.1. Não há opção de host.
  • Toda requisição HTTP e todo upgrade exigem Host igual a 127.0.0.1:<porta> ou localhost:<porta> (defesa contra DNS rebinding), senão 421. Nunca há cabeçalhos CORS.
  • HTTP aceita só GET e HEAD (senão 405). Sem --ui, tudo fora de /rpc é 404. Com --ui, só arquivos dentro do diretório (pelo caminho real): .., barra invertida, NUL, arquivos com ponto no início e links simbólicos para fora dão 404; um caminho sem extensão que não é arquivo devolve index.html. Não há listagem de diretório. Toda resposta leva Content-Security-Policy, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, X-Frame-Options: DENY e Cache-Control: no-store.
  • O WebSocket fica em /rpc e exige Origin permitido (senão 403). No máximo 4 conexões abertas (a quinta recebe 503). Mensagens só de texto (binário fecha com 1003), até MAX_REQUEST bytes, no máximo 20 por segundo com rajada de 40 (acima disso fecha com 1008). session.open com o token tem de chegar em 5 s. Só uma conexão autenticada por vez: a nova fecha a anterior com o código 4000 (substituída). Um cliente que não lê e acumula mais de MAX_OUTBOUND bytes é desligado.
  • VARANDA_SERVE_OPEN_TIMEOUT_MS existe só para os testes: encurta o prazo do session.open (1 a 5000 ms), nunca o alonga.

Ctrl-C (SIGINT) ou SIGTERM fecha as conexões (código 1001), espera a sessão terminar, libera o diretório de dados e sai com 0. Erros internos aparecem só em stderr como erro interno: <mensagem>, nunca para o cliente.

Testes e lint

Na raiz:

npm test
npm run lint

npm test executa node scripts/run-tests.js --workspaces: um só pool de processos filhos com os test/*.test.js de todos os workspaces, VARANDA_TEST_CONCURRENCY por vez, cada arquivo rodando a partir do diretório do seu workspace (com prazo por arquivo: VARANDA_TEST_TIMEOUT_MS, padrão 180000). O script de teste de cada workspace é node ../../scripts/run-tests.js, que faz o mesmo para um workspace só (npm test -w <workspace>); um workspace com outro script de teste faz a execução da raiz falhar, em vez de ficar de fora. Com mais de um arquivo por vez, os mais lentos começam primeiro, pela duração da última execução, guardada em node_modules/.cache/varanda-test-durations.json (VARANDA_TEST_DURATIONS muda o caminho; arquivo nunca medido começa primeiro, e sem o arquivo vale a ordem da lista). Sem a variável, o pool é a metade inteira dos núcleos da CPU, no máximo 4 (4 num Mac de 12 núcleos, 2 numa máquina de 4 núcleos), porque vários testes medem tempos abaixo de 100 ms que mudam sob carga; VARANDA_TEST_CONCURRENCY=1 roda um arquivo por vez, com a saída ao vivo. Com mais de um arquivo por vez, a saída de cada um sai num bloco ao terminar (ordem de término, sem intercalação), e o resumo lista # falha: <arquivo> para cada falha antes de # N arquivo(s) de teste, M falha(s). VARANDA_TEST_SHARD=I/N roda só os arquivos cuja posição i (base 0, na lista ordenada ou na ordem da linha de comando) satisfaz i % N == I - 1; um fragmento sem arquivos sai com falha (# nenhum arquivo neste fragmento), e um valor inválido também. Se um teste de tempo falhar, rode-o sozinho (node <arquivo>) ou com VARANDA_TEST_CONCURRENCY=1 antes de culpar a sua mudança.

Para iterar mais rápido, npm test -- --affected=origin/main roda só os workspaces que uma mudança desde origin/main pode alcançar (scripts/affected.js). Conta como mudança o que mudou desde a base comum com HEAD: commits, edições com ou sem stage e arquivos novos que o git não ignora. A referência também pode ser uma árvore (o git write-tree da última execução verde), comparada como está. Um workspace alterado roda inteiro. Outro roda quando algum arquivo dele cita um arquivo alterado, direta ou indiretamente: caminho relativo, caminho a partir da raiz, path.join a partir de __dirname, nome de pacote em require ou import, ou workspace listado nas dependências do seu package.json. Mudar o package.json da raiz, o package-lock.json, scripts/ ou o package.json de qualquer workspace roda todos. Sem mudança, ou sem workspace alcançado, sai com 0 e diz por quê. A busca por citações é heurística. A CI de um PR usa a mesma seleção, a partir do pai do commit de merge de teste (HEAD^1): o job affected pula os jobs fragmentados de um workspace que a mudança não alcança, e o job others roda com --affected. Cada push na main roda todos os workspaces, e é ele que pega uma dependência que a busca não vê. npm test -- --list (com ou sem --affected=<ref>) só imprime os workspaces que rodariam, um por linha, sem rodar nenhum.

Um workspace:

npm test -w packages/rpc
npm test -w packages/core
npm test -w apps/cli
npm test -w apps/site

Servidor de desenvolvimento do site estático (apps/site):

npm run dev -w apps/site

Abre em http://127.0.0.1:4173/. Publicação em GitHub Pages: docs/site.md.

Em cada pull request e em cada push para main, o workflow .github/workflows/ci.yml roda em ubuntu-24.04, no Node 20 e no 24. Em cada versão, oito jobs rodam em paralelo: packages/core em dois fragmentos, apps/cli em dois (VARANDA_TEST_SHARD 1/2 e 2/2), packages/web-member em três (1/3, 2/3 e 3/3) e others. O job others roda o lint, o npm test da raiz para os workspaces que restam e a demo, que deve terminar com DEMO OK. packages/core, apps/cli e packages/web-member são pulados nesse npm test, porque têm job próprio. Um workspace acrescentado depois roda ali automaticamente. Cada job começa com npm ci --ignore-scripts e define VARANDA_TEST_CONCURRENCY=1. O paralelismo da CI vem dos jobs. Os checks test (20) e test (24), um por versão, são os que a regra da main exige. Cada um só passa se os oito jobs daquela versão passaram, e falha se algum falhou, foi cancelado ou pulado. Localmente os quatro passos não mudam: npm ci (ou npm install), npm run lint, npm test e npm run demo.

Um arquivo, a partir da raiz:

node apps/cli/test/serve.test.js

npm test -w apps/app roda apps/app/test/*.test.js: pwa, sw, outbox, discovery, recoveryPolicy, pwa-boot, persist, config e format. Em packages/core, test/bare-load.test.js confere o núcleo no runtime Bare (parte de npm test -w packages/core).

Os testes de rede usam uma DHT local em processo (hyperdht/testnet por apps/cli/test/helpers/net.js), presa a 127.0.0.1. Nenhum teste usa a DHT pública. npm run lint roda o standard em todo o repositório. Detalhes em docs/development.md.

Layout de armazenamento

Arquivos JSON de estado são gravados num arquivo temporário e renomeados por cima do destino. store/ (modo 0700) contém a chave primária do Corestore; a chave que assina o diário deriva dela. id show e seed key imprimem só chaves públicas.

Membro (data/alice, data/bob)

  • store/ — Corestore do diário e das réplicas seguidas.
  • quarantine/ — Corestore só da busca do bloco 0 de um diário ainda não aceito. O sync apaga esse diretório ao abrir (depois do lock de store/) e de novo ao fechar. Não é estado.
  • config.json — { "v": 1, "role": "member", "association": "<hex64>" }, escrito por id create.
  • follows.json — { "v": 1, "follows": ["<hex64>"] }, chaves únicas em ordem. Com o bloco 0 gravado, cada mudança também vira um registro follow no diário.
  • blocklist.json — { "v": 1, "snapshot": <lista assinada> }, modo 0600: a lista de bloqueio mais nova que este nó aceitou. Só chaves públicas. O arquivo blocklist.json.prev guarda a mesma lista: se o principal ficar ilegível, o nó lê a cópia e a repõe.

Semeador (data/seeder)

  • store/ — réplicas admitidas. Todo core aqui está listado em admitted.json.
  • quarantine/ — busca do bloco 0 na admissão. Apagado em cada seed (depois do lock de store/) e de novo ao fechar. Não é estado.
  • config.json — { "v": 1, "role": "seeder", "association": "<hex64>" }, escrito pelo primeiro de seed key, seed cert add e seed.
  • seeder-key.json — par Noise do semeador, modo 0600: v, publicKey (hex64) e secretKey. Criado por seed key. O comando não imprime secretKey.
  • seeder-cert.json — certificado do semeador em JSON indentado, escrito por seed cert add.
  • blocklist.json — como no membro: a lista de bloqueio mais nova aceita, com a cópia blocklist.json.prev. Um arquivo ilegível é guardado como blocklist.json.ilegivel-<ms> e a cópia o substitui; um arquivo ausente com cópia também é reposto. Sem cópia (ou com uma cópia que não verifica), o semeador não admite diários novos (rejected com blocklist-pending; quem ele já serve continua recebendo admitted) até receber uma lista verificada; a trava vale de novo a cada partida enquanto o blocklist.json.ilegivel-<ms> guardado estiver lá e nenhuma lista verificada também (seed status e /health mostram blocklistHeld). Se o arquivo não puder ser movido, a partida falha (erro: lista de bloqueio ilegível).
  • admitted.json — único arquivo de estado dos diários servidos: { "v": 1, "admitted": { "<hex64>": <certificado de membro> }, "media": { "<hex64 do núcleo>": { "diary": "<hex64>", "seq": <n> } } }. Um arquivo antigo, sem media, continua valendo. A chave entra nesse arquivo antes do core abrir em store/. Uma chave em descarte permanece no arquivo até a limpeza do core terminar.

Associação (data/assoc)

  • association.json — par de chaves da associação, modo 0600. assoc show imprime só a chave pública.
  • members.jsonl — uma linha JSON por certificado de membro, exatamente member, ageBand, method e date.
  • seeders.jsonl — uma linha JSON por certificado de semeador: {"seeder":"<hex64>","date":"<ISO>"}. Sem assinatura e sem segredo.
  • issuers.jsonl — uma linha JSON por certificado de emissor do serviço de conta: {"issuer":"<hex64>","date":"<ISO>"}. Sem assinatura e sem segredo.
  • moderators.jsonl — uma linha JSON por certificado da moderação: {"moderator":"<hex64>","date":"<ISO>"}. Sem assinatura e sem segredo.

Moderação (data/mod)

Fica na máquina do operador, como a associação.

  • config.json — { "v": 1, "role": "moderator", "association": "<hex64>", "seeder": "<hex64>" }, escrito por mod init; seeder (a chave Noise do semeador para onde a lista é publicada) só existe depois de mod init --seeder.
  • moderator.json — par de chaves da moderação, modo 0600. mod init imprime só a chave pública.
  • moderator-cert.json — certificado da moderação assinado pela associação, escrito por mod cert add.
  • blocklist.json — { "v": 1, "snapshot": <lista assinada> }, modo 0600: a última lista gravada. Ao trocar a chave da moderação, copie este arquivo para o diretório novo.
  • moderation.jsonl — uma linha JSON por mudança, modo 0600: {"op":"block","member":"<hex64>","seq":<n>,"date":"<ISO>","source":"operacao"} (op block ou unblock; em revoke-issuer e unrevoke-issuer o campo é issuer; source é painel para as linhas de mod apply e operacao para os outros comandos mod, e uma linha antiga sem o campo conta como operacao). Sem assinatura e sem segredo.

Exemplo de linha em members.jsonl (a data real é a da emissão):

{"member":"<hex64>","ageBand":"18+","method":"stub","date":"2026-01-01T00:00:00.000Z"}

Formato dos dados

Bloco 0 e registros

{ "type": "member-cert", "cert": { "v": 1, "member": "<hex64>", "ageBand": "18+", "method": "stub", "date": "2026-01-01T00:00:00.000Z", "association": "<hex64>", "signature": "<128 hex minúsculos>" } }
{ "type": "profile", "name": "Alice", "bio": "protótipo", "at": "2026-01-01T00:00:00.000Z" }
{ "type": "post", "text": "primeira publicação", "at": "2026-01-01T00:00:00.000Z", "replyTo": null }
{ "type": "post", "text": "também li", "at": "2026-01-01T00:00:00.000Z", "replyTo": { "author": "<hex64>", "seq": 2 } }

at é new Date().toISOString() na hora da escrita e tem de ser canônico. Serve para ordenar. Quem lê pula bloco que não é um registro válido e não renumera os outros. A referência de uma publicação é <hex64>:<seq>.

O feed ordena por (at, autor, seq). --limit <n> fica com as últimas n depois de tirar as publicações futuras. Para paginar para trás, --before <cursor> devolve só as publicações anteriores ao cursor, {"at","author","seq"} em JSON, o mesmo de feed.read. Quando a página vem cheia, feed imprime o próximo cursor na saída de erro (com --json, no campo next, que é null quando a página não vem cheia; se a última página tiver exatamente n itens, ela também traz o cursor e a seguinte volta vazia). Um cursor inválido é erro de uso. Item: autor, nome (ou nulo), @nome (ou nulo), seq, at, texto, replyTo e media (as descrições das fotos, ou nulo).

Certificado do semeador (seeder-cert.json), também com exatamente estas chaves:

{
  "v": 1,
  "seeder": "<hex64 da chave Noise>",
  "date": "2026-01-01T00:00:00.000Z",
  "association": "<hex64>",
  "signature": "<128 hex minúsculos>"
}

Assinatura

A assinatura cobre bytes UTF-8 de linhas separadas por um único LF, sem LF no final. O texto assinado não é a saída de JSON.stringify. O hex entra em minúsculas.

Certificado de membro, seis linhas:

varanda-cert-v1
<member hex64>
<faixa etária>
<método>
<data ISO>
<association hex64>

Certificado de semeador, quatro linhas:

varanda-seeder-v1
<seeder hex64>
<data ISO>
<association hex64>

A associação assina esses bytes com a chave secreta Ed25519 dela. A assinatura no JSON é esse resultado em 128 hex minúsculos.

Diante da chave do diário, a verificação devolve o primeiro motivo nesta ordem: malformed, member-mismatch, untrusted-association, bad-signature. No semeador a ordem é malformed, seeder-mismatch, untrusted-association, bad-signature. no-cert é bloco 0 ausente. not-in-log é bloco 0 presente que não é um registro member-cert válido. fork é histórico reescrito. timeout é prazo da busca do bloco 0 esgotado, no semeador que responde a um announce.

Chave do diário

O Corestore deriva o par Ed25519 que assina o diário a partir da chave primária do store, criada neste dispositivo, e deriva a chave do core de um manifesto de um único assinante. A chave pública do diário, a que id create imprime, é a chave do core. Ela não coincide byte a byte com a chave pública crua do assinante. Só o dispositivo que tem esse store/ acrescenta blocos.

Leitura: futuro e fork

Publicação com Date.parse(at) mais de 24 horas à frente de quem lê sai do feed e entra na lista future (<hex64>:<seq>). O aviso é aviso: publicação <ref> ignorada (future). A ordem dos itens que ficam continua determinística para aquele relógio.

Diário com fork diferente de zero foi reescrito por quem tem a chave. O semeador deixa de semeá-lo. O sync apaga a réplica e avisa em stderr aviso: diário <8 hex> ignorado (fork). O feed emite o mesmo aviso e só lê; o próximo sync é que apaga a cópia local.

Limitações e próximos passos

Limites desta fase:

  • Um bloco tem no máximo 16 KiB. Um diário tem no máximo 100 000 blocos e 64 MiB. Publicar além disso falha com erro: limite do diário atingido, e o semeador descarta um diário acima do limite com motivo quota.
  • No máximo 64 conexões do enxame por processo. As conexões externas do semeador (WebSocket) têm um limite separado, VARANDA_MAX_EXTERNAL (padrão 32).
  • No máximo 4096 diários anunciados por par.
  • Um par que viola o protocolo é desconectado.
  • O semeador aceita até 10 anúncios por segundo de cada par (rajada de 20); um par cujo certificado falha 16 vezes é desconectado.
  • No máximo 4095 diários seguidos: follow além disso falha com erro: limite de diários seguidos atingido.
  • sync --once espera pares que não são semeadores verificados por no máximo 5 s no total, quantos forem. Sem um semeador verificado que confirme a sua cópia, o resultado é sync done (sem confirmação de semeador): ninguém garantiu guardar o seu diário.
  • Cada conexão aceita até 100 mensagens por segundo (rajada de 4160); um par acima disso é desconectado.
  • Em sync --once, a busca do bloco 0 de um diário seguido dura no máximo 15 s; se ninguém o entregar, o diário aparece como não anunciado e o resultado pode ser sync done sem ele.
  • log --author <chave> exige dados locais do diário (erro: sem dados locais para este diário caso contrário).
  • A confirmação do celular não substitui a verificação de idade, feita à parte; o certificado v2 continua com ageBand: unchecked.
  • O app nativo e a CLI ainda colam o certificado v1 emitido pela associação (assoc certify); só a versão web hospedada recebe o certificado v2 do serviço de conta. Nós de antes desta mudança rejeitam um certificado v2 como malformed, então o semeador e todo membro nativo ou da CLI precisam atualizar antes da primeira emissão v2.
  • A identidade piloto da versão web mantém o certificado v1 (um diário não aceita um segundo certificado). Ela pode vincular a conta ao celular verificado e ganhar um @nome pelo registro de @nome, mas o certificado dela continua v1.
  • O @nome troca no máximo uma vez a cada 7 dias e um nome já usado por um membro não vai para outro; um nó antigo ou um seguidor que ainda não sincronizou pode mostrar por um tempo o nome anterior.
  • A lista de bloqueio é obedecida só por nós atualizados e honestos: um nó de antes da PR B2 não a aplica, um app modificado ainda pode falar direto com a conta bloqueada, e o app oficial da própria conta bloqueada guarda o diário e pode servi-lo a quem já conhece a chave de descoberta. A versão web sem rede aplica a lista que já guardou e só recebe uma nova pelo semeador. Bloquear não apaga nada do aparelho do autor. Veja docs/verification.md seção 13.
  • A lista tem no máximo 4096 contas bloqueadas e 64 emissores revogados. Cada conexão troca no máximo uma lista a cada 10 s e é derrubada depois de 5 mensagens inválidas no canal varanda/blocklist/1.
  • Só o nó hospedado denuncia (a versão web hospedada e o app instalado com a instalação): o app com configuração manual, o varanda-serve e a CLI não têm como assinar ou enviar uma denúncia (a folha avisa), e só quem vinculou a conta denuncia, até 20 vezes a cada 24 horas. O trecho citado da publicação é o que quem denuncia enviou e não é conferido pelo serviço, e a pessoa denunciada não vê nada. Veja docs/verification.md seção 14.
  • As sessões do painel acabam quando o serviço account reinicia. A lista que o painel mostra como publicada é o espelho verificado da última lista que o operador confirmou com mod apply, e o blocklist.json do operador é a que vale; "aplicado" é a palavra do operador, e a propagação segue as regras do varanda/blocklist/1.
  • Certificados de membro individuais não são revogáveis (bloqueie a chave do diário). A chave do emissor do serviço de conta é revogada com mod revoke-issuer; depois disso gere outra (account key), certifique (assoc certify-issuer), account cert add, reinicie o serviço e peça que os membros vinculem de novo, porque os certificados v2 antigos deixam de valer. A reemissão automática fica para uma PR futura.
  • O app pagina para trás por cursor (before em feed.read e log.read: 30 e depois páginas de 31 publicações, páginas de 36 blocos no diário), e os comandos feed e log da CLI paginam do mesmo jeito com --limit e --before. Não há paginação para a frente (since); dados novos pedem recarregar a página mais nova.
  • A Espiadinha (segunda aba) só existe no nó hospedado (versão web hospedada e app instalado com a instalação): o app com configuração manual e o varanda-serve avisam disso. Cada página abre uma conexão curta com o semeador (uma conexão externa a mais, entre as conexões externas que ele aceita, VARANDA_MAX_EXTERNAL, padrão 32; com muitos membros online o semeador responde lotado (a mensagem do nó, "Semeador ocupado; tente novamente em instantes.", não muda) e a tela mostra "Muitas pessoas conectadas agora. Tente de novo em instantes."; medido em laço local, 40 membros conectados com o padrão de 32 dão 32 vagas ocupadas e 8 recusas, e cada leitura segura uma vaga por cerca de 10 a 20 ms. Quadros grandes demais vindos do semeador cortam a ligação), o custo cresce de forma linear com o número de diários do semeador (páginas cortadas em 25 s ou 16 MiB aparecem como incompletas), nada é guardado no aparelho além da memória da página, nomes são o melhor possível, mostra até 3 publicações por diário (respostas, citações e republicações incluídas) e a data é a que o autor escreveu. Regra e detalhes em docs/rpc.md (5.22) e docs/verification.md seção 17. A pesquisa por assunto da Espiadinha acha só palavras inteiras (sem prefixo, sem acentos nem alfabetos fora de a-z depois de tirar os acentos), em ordem de data e sem pesos, apenas no que o semeador indexou na memória (pode estar incompleto), sem "assuntos do momento"; uma publicação ainda não pode ser apagada, então continua pesquisável até o diário sair do semeador (docs/protocol.md seção 5).
  • Os Avisos (abrem pelo sino no canto direito da barra do topo e na faixa do Diário, não são aba; a barra de baixo tem seis abas onde o nó é hospedado e quatro na configuração manual e no varanda-serve, e a lista Seguindo abre por "N seguindo" no Diário) só existem no nó hospedado (versão web hospedada e app instalado com a instalação): o app com configuração manual, o varanda-serve e a CLI mostram "só na versão web". Quem começou a seguir você aparece numa linha que abre o perfil da pessoa, onde fica o "Seguir", e quem responde, cita ou menciona (@nome no texto) você aparece numa linha que abre a conversa; sem contagem nem lista de seguidores dentro de Avisos e sem rota HTTP nova para eles (a contagem e a lista públicas de seguidores nos perfis usam as rotas /index/follows/..., por decisão dos donos do projeto; Termos e Política na versão 12, docs/verification.md seção 74); o semeador guarda os índices só em memória (canais varanda/notices/1, só de seguir, e varanda/notices/2, com os quatro tipos, docs/protocol.md) e cada leitura usa uma conexão externa curta a mais, como a Espiadinha. Detalhes em docs/rpc.md (5.28) e docs/verification.md seções 20 e 35. O push da versão web hospedada (seguir, resposta, citação, menção, curtida e republicação; o aviso do sistema segue só na web) é outro caminho e entra nesta fase: "Avisos push" acima e docs/verification.md seção 38.
  • O app sincroniza sozinho sempre que está aberto e com rede, também com dados móveis; a preferência por Wi-Fi não existe (issue #48). Toda leitura de membro ainda interrompe e reinicia a rodada contínua (issue #66); o app reduz o efeito com leituras em lote (profile.read com até 100 chaves, no máximo um pedido por segundo), uma janela de 5 s antes das buscas de fundo e a pílula "ver novidades" no lugar de recarregar sozinho. A pílula é só uma dica das linhas downloaded, nunca uma contagem. Veja docs/app.md.

Fora desta fase:

  • Verificação de idade real. Hoje o operador de assoc certify afirma --age-band. Comentário TODO(phase1): the real age-check vendor decides here; today the operator asserts the age band. em packages/core/lib/assoc.js. O mesmo limite está em docs/protocol.md (certificados).
  • Notificações push quando um diário seguido cresce. Comentário TODO(phase1): push notifications when a followed log grows. em packages/core/lib/sync.js e em docs/protocol.md (sync). Esse caso, um aviso quando um diário seguido cresce, continua fora. Os seis eventos (seguir, resposta, citação, menção, curtida e republicação) já têm push na versão web hospedada, com adesão em Ajustes. Sem contagem nem lista de seguidores dentro de Avisos (a contagem e a lista públicas ficam nos perfis). O app nativo, o varanda-serve e a CLI não têm push.
  • Recuperação da chave do diário com chaves limiar FROST. Comentário TODO(phase2): threshold-key (FROST) recovery of this key. em docs/protocol.md (identidade). A chave fica no store/ deste dispositivo.
  • Denúncias pela CLI (a denúncia pela versão web e pelo app instalado, inclusive do perfil de outro membro, o painel e a lista de bloqueio assinada já existem). Conversas completas e perfis de quem a pessoa não segue só pela versão web hospedada (índice de engajamento do semeador e leitura sob demanda; docs/protocol.md seções 5 e 7). Prazos e retenção das denúncias seguem em aberto (issue #38). Certificado de membro e certificado de semeador não expiram e não são revogados individualmente; só a chave de emissor é revogada, pela lista.
  • A comparação de fotos, GIFs e vídeos curtos com listas de hashes de material ilegal (docs/design.md, Moderação). Fotos, GIFs e um vídeo curto já saem na web hospedada e no app instalado; o navegador só aceita um arquivo de vídeo que já cabe. Veja docs/verification.md seções 16, 181 e 183.
  • Empacotamento Pear e distribuição fora das lojas. O aplicativo Expo (apps/app) já roda o núcleo no Bare (iOS e Android), e a versão web roda o nó no próprio navegador (sincronizando pelo semeador) ou usa o varanda-serve na máquina local; ver docs/app.md, docs/verification.md e docs/development.md. O CLI continua sendo um programa Node sem etapa de compilação.
  • Relay de certificados por seguidores. O sync anuncia só o próprio diário (packages/core/lib/sync.js envia announce da chave local e ignora announce recebido). Um seguidor não apresenta ao semeador o certificado de outra pessoa. Se a autora nunca sincronizou, o semeador não tem a cópia, mesmo que um seguidor já a tenha. Não há comentário TODO no código para esse relay. docs/protocol.md registra que o announce permanece sem autenticação de propósito: qualquer par pode pedir a admissão, e só entra o diário cujo bloco 0 passa na verificação.

Códigos de saída

Código Quando
0 Sucesso. sync --once imprime sync done (ou sync done (sem confirmação de semeador) quando nenhum semeador verificado confirmou a cópia do seu diário). seed e a DHT local saem com 0 depois de SIGINT ou SIGTERM. A demo imprime DEMO OK.
1 Falha. Mensagem em stderr: erro: <mensagem>. Exemplos: erro: certificado inválido (untrusted-association), erro: certificado do semeador não encontrado (use seed cert add), erro: associação diferente da configurada, erro: diretório de dados em uso, erro: porta em uso. sync com metas não cumpridas também sai 1 e escreve sync failed: <erros> na saída padrão.
2 Uso. O analisador escreve uso: <mensagem> e em seguida a ajuda. Exemplos: uso: bootstrap inválido <valor>, uso: bootstrap inválido (vazio), uso: dht-host inválido, uso: falta o valor de --text, uso: opção desconhecida <flag>. Um comando que recusa a própria linha escreve só uso: <mensagem>, sem repetir a ajuda: uso: informe --text <texto>, uso: informe --seeder <hex>, uso: informe --cert-file <arquivo>, uso: informe a chave do diário, `uso: node bin/varanda.js seed [key

Releases

Packages

Contributors

Languages