Stealth Observability (Superadmin)

17.W Stealth Observability (Superadmin)#

Scaffold inicial para os dashboards administrativos de fingerprint/warmup. Os endpoints abaixo já existem e mantem shape estável mesmo antes das tasks que populam os campos de fingerprint/warmup.

GET/v1/admin/fingerprint-audit#

Resumo frota-wide de diversidade de plataforma/spec/cidade + violacoes de coerencia.

Auth: Superadmin

Resposta 200:

json 
{
  "total_instances": 0,
  "by_platform": {},
  "by_utls_spec": {},
  "by_city": {},
  "coherence_violations": {
    "city_mismatch_ddd": 0,
    "push_name_equals_api": 0,
    "mcc_equals_000": 0,
    "platform_spec_mismatch": 0
  },
  "warmup_distribution": {}
}

Notas:

  • total_instances e contado na frota ativa.
  • Os mapas podem vir vazios no bootstrap inicial; a shape não muda.
  • O frontend admin em /platform/fingerprint-audit consome este payload.

GET/v1/admin/warmup-audit#

Resumo frota-wide da distribuição de warmup, instâncias perto do daily cap e próximas promocoes.

Auth: Superadmin

Resposta 200:

json 
{
  "total_instances": 0,
  "by_phase": {},
  "near_daily_cap": [],
  "next_promotions": []
}

Notas:

  • O endpoint existe antes dos produtores finais de warmup para permitir integração antecipada do dashboard.
  • O frontend admin em /platform/warmup-audit consome este payload.

Fingerprint uTLS Pool (Superadmin)#

Profiles deste pool são atribuidos somente a instâncias novas. Instâncias já pareadas nunca são mutadas, e a fonte de verdade em runtime contínua sendo o campo tenant fingerprint_utls_spec.

Built-ins entram como staging; WA Probe e o único gate que promove um profile para active.

GET /v1/admin/fingerprint-pool/profiles#

Retorna todos os profiles uTLS do master DB com status, peso, último probe e estado de burn.

Auth: Superadmin

PATCH /v1/admin/fingerprint-pool/profiles/{profileName}#

Atualiza campos operacionais de um profile. Permite weight entre 0 e 1000 e status igual a staging, deprecated ou burned. active não e aceito neste endpoint: WA Probe contínua sendo o único gate de promoção para active.

Auth: Superadmin

Body:

json 
{
  "status": "deprecated",
  "weight": 3
}

POST /v1/admin/fingerprint-pool/profiles/seed-builtins#

Seed idempotente dos profiles compilados no binario atual. Em 2026-05-08, o builtin disponível e safari-mac-17.

Auth: Superadmin

POST /v1/admin/fingerprint-pool/profiles/{profileName}/wa-probe/{proxyId}#

Executa um WhatsApp QR Probe descartavel através do proxy selecionado usando o profile uTLS escolhido. Não pareia instância de cliente.

Auth: Superadmin

Metricas relacionadas: biazap_fingerprint_utls_pool_active_size, biazap_fingerprint_utls_assignments_total, biazap_fingerprint_utls_probe_total, biazap_fingerprint_utls_burn_total.

GET/v1/admin/app-version#

Retorna o estado singleton do rollout de AppVersion mantido pelo worker no master DB. O worker consulta o upstream do whatsmeow a cada 14 dias, válida o semver detectado e apenas faz stage; a aplicação na frota depende de aprovacao explicita por superadmin.

Auth: Superadmin

Resposta 200:

json 
{
  "current_catalog_version": "2.3000.1034566421",
  "detected_upstream_version": "2.3001.1",
  "staged_pending_approval_version": "2.3001.1",
  "canary_rollout": {
    "active": true,
    "started_at": "2026-04-21T15:00:00Z",
    "instance_ids": [
      "inst-a",
      "inst-b",
      "inst-c",
      "inst-d",
      "inst-e"
    ],
    "fleet_applied_at": null
  },
  "last_fetch_at": "2026-04-21T14:00:00Z"
}

Notas:

  • staged_pending_approval_version fica vazio quando o upstream não detecta um valor mais novo que o catalogo atual.
  • canary_rollout.active=true significa que a versão staged já foi aprovada e está observando 5 instâncias por 72h antes do fleet apply.
  • O worker persiste o estado em app_version_states (singleton id=1) para sobreviver a restart.

POST/v1/admin/app-version/approve#

Aprova a versão staged e inicia o rollout canary em 5 instâncias conectadas escolhidas aleatoriamente. Não recebe body.

Auth: Superadmin

Resposta 200:

json 
{
  "current_catalog_version": "2.3000.1034566421",
  "detected_upstream_version": "2.3001.1",
  "staged_pending_approval_version": "2.3001.1",
  "canary_rollout": {
    "active": true,
    "started_at": "2026-04-21T15:00:00Z",
    "instance_ids": [
      "inst-a",
      "inst-b",
      "inst-c",
      "inst-d",
      "inst-e"
    ],
    "fleet_applied_at": null
  },
  "last_fetch_at": "2026-04-21T14:00:00Z"
}

Resposta 400:

json 
{
  "error": "no staged app version pending approval"
}

Notas:

  • O canary escreve fingerprint_app_version apenas nas 5 instâncias selecionadas; o restante da frota contínua com current_catalog_version.
  • Depois de 72h sem falha observada, o worker promove a staged para current_catalog_version, aplica na frota toda e emite stealth.app_version_fleet_applied.
  • Se o fetch upstream falhar ou for rejeitado nas sanity checks, o worker mantem o catalogo atual, loga WARN e incrementa biazap_appversion_fetch_failed_total.

POST/v1/admin/instances/{instanceId}/warmup/bypass#

Concede um bypass temporario do warmup v2 para uma instância especifica. O worker passa a ignorar os gates de warmup_phase, daily cap e janela horaria enquanto a chave Redis do bypass estiver válida.

Auth: Superadmin

Body JSON:

json 
{
  "reason": "sla unblock",
  "ticket_id": "SUP-123",
  "auto_expire_at": "2026-04-22T12:00:00Z"
}

Campos:

  • reason obrigatório.
  • ticket_id obrigatório.
  • auto_expire_at opcional. Quando omitido, a API usa TTL padrão de 24h.

Resposta 200:

json 
{
  "instance_id": "84c2e480-...",
  "token": "0f3f6f15-3fa2-46f0-b7a7-d7790f9e5e36",
  "expires_at": "2026-04-22T12:00:00Z"
}

Notas:

  • O grant grava uma linha em stealth_audit_events com event_type = "warmup.bypass_granted".
  • O bypass e rate-limited por instância no Redis para evitar uso repetitivo sem triagem humana.
  • O valor retornado em token e apenas auditoria/operação; o gate do worker válida a chave Redis por instância.

POST/v1/admin/instances/{instanceId}/hygiene/apply#

Forca a aplicação imediata dos defaults de hygiene na instância conectada e persiste hygiene_skip=false para os próximos connects.

Auth: Superadmin

Body JSON: nenhum.

Resposta 200:

json 
{
  "instance_id": "84c2e480-...",
  "company_id": 1,
  "hygiene_skip": false
}

Notas:

  • O endpoint reutiliza o mesmo applier deterministico do worker (FingerprintSeed -> push_name/avatar/status).
  • O endpoint e rate-limited por instância no Redis para evitar uso repetitivo sem triagem humana.
  • A chamada falha se a instância não tiver sessão WhatsApp conectada no worker; nesse caso hygiene_skip permanece inalterado.
  • Cada alteração aplicada gera stealth.audit_event / hygiene.applied com event_data.type em push_name, photo ou status.

Regras de alerta seedadas#

No primeiro boot, a API passa a semear também estas AlertRule padrão para o modulo Stealth:

  • FingerprintPlatformDiversityLow
  • UTLSSpecsTooFew
  • ConnectionBurst
  • WarmupReceiveOnlyBacklog
  • BanRateSpike
  • ProxyPoolCityStarved
  • StealthDebugModeStuck
  • StealthAuditTableUnbounded