Alertas Push — ntfy.sh

Canal de alertas push para equipe técnica/admin via ntfy.sh

---

1. Visão Geral

O sistema utiliza ntfy.sh como canal complementar de alertas push para a equipe técnica. Não substitui WhatsApp (que continua para alertas a gestores de escola).

Características:

• Zero dependências (puro HTTP fetch)
• Sem infra própria (SaaS gratuito)
• Sem autenticação por token (segurança via tópico secreto)
• Graceful degradation: se NTFY_TOPIC não configurado, alertas são ignorados silenciosamente

---

2. Setup

2.1 Instalar o app ntfy

• Android: Google Play ou F-Droid
• iOS: App Store
• Desktop: Web app

2.2 Gerar tópico secreto

# Gerar hash de alta entropia (32 caracteres hex)
openssl rand -hex 16
# Exemplo: a7f3b2c9e1d4f6a8b3c5d7e9f1a2b4c6

2.3 Configurar secret no Supabase

Adicionar NTFY_TOPIC nos secrets do Supabase com o hash gerado acima.

2.4 Inscrever no tópico

No app ntfy, inscrever-se no tópico usando o mesmo hash:

1. Abrir o app
2. Tocar em "+" (adicionar assinatura)
3. Colar o hash como nome do tópico
4. Salvar

---

3. Gatilhos de Alerta

Evento	Prioridade	Tags	Origem	Cooldown
CRON Faturamento falha crítica (3x)	urgent	⚠️💀	faturamento-cron	N/A
CRON Manutenção falha crítica (3x)	urgent	⚠️💀	maintenance-cron	N/A
Sessão WhatsApp desconectada	urgent	💸⚠️	maintenance-cron	24h
Token revogado reutilizado (não-logout)	high	🚔⚠️	auth-helpers.ts	N/A
Lockout Tier 2 (6+ falhas, 10min)	high	⚠️🔒	portal-escola	5min
Lockout Tier 3 (10+ falhas, 60min)	urgent	🚨💀	portal-escola	5min
Burst bloqueado (150 req/5s)	urgent	🔥🤖	portal-escola	5min
Rate limit escola 100%	high	⛔🏫	portal-escola	15min
Rate limit escola 70% (pico)	high	⚠️📈	portal-escola	15min
Rate limit OTP aluno esgotado	high	⚠️💸	portal-escola	15min
Rate limit OTP responsável esgotado	high	⚠️💸	portal-escola	15min

---

4. Helper: _shared/ntfy-helper.ts

import { enviarAlertaPush } from '../_shared/ntfy-helper.ts';

await enviarAlertaPush({
  titulo: 'Título do Alerta',
  mensagem: 'Descrição detalhada do que aconteceu.',
  prioridade: 'high',  // min | low | default | high | urgent
  tags: ['warning'],    // emojis ntfy
});

Regras de uso

1. SEMPRE usar await — Deno Deploy pode podar a execução se fire-and-forget
2. NUNCA propagar exceções — O helper já tem try/catch interno
3. Não usar como substituto de SMS — Canal complementar para equipe técnica
4. Títulos DEVEM ser ASCII puro — Emojis/unicode no campo titulo causam TypeError: not a valid ByteString no Deno. O helper aplica sanitizeForHeader() automaticamente como defesa em profundidade, mas prefira usar texto ASCII e representar emojis via tags (ex: ['rotating_light', 'warning'])

---

4.1 LGPD — proibido enviar PII para o ntfy

ntfy.sh é serviço de terceiro. Enquanto não migrarmos para self-hosted, nenhum dado de pessoa física pode sair no payload (título/mensagem/tags). Use o helper canônico de assunto:

import { formatAlertSubject } from '../_shared/ntfy-helper.ts';

const subject = formatAlertSubject({
  papel: payload.principal_role,    // ex: 'coordenador'
  escola_nome: escola?.nome,        // PJ — não é PII
  escola_id: payload.escola_id,     // fallback
});
// → "coordenador @ Escola Municipal Boa Vista"
// fallback → "coordenador @ escola:a1b2c3d4…"

await enviarAlertaPush({
  titulo: 'Brute Force Senha',
  mensagem: `${subject} — 5 tentativas em 60s`,
  prioridade: 'high',
  tags: ['rotating_light'],
});

Proibido: nome_completo, e-mail, telefone, CPF, JID. Para correlação interna, use uid:${id8}. Refs: docs/lgpd/PII_LOG_MASKING_PLAN.md Etapa 3, docs/audits/AUDIT_PII_LOGS_LGPD_2026-05-08.md.

---

5. Segurança

• O tópico ntfy funciona como "senha" — quem não sabe o nome não recebe
• Usar hash de alta entropia (openssl rand -hex 16)
• Não expor o tópico em logs, código-fonte ou documentação pública
• Futuro: adicionar NTFY_TOKEN para ACL se necessário

---

6. Prioridades ntfy

Prioridade	Comportamento no celular
min	Sem som, sem vibração
low	Sem som
default	Som padrão
high	Som alto, vibração longa
urgent	Som persistente, vibração contínua, bypassa Não Perturbe

---

Referências

• supabase/functions/_shared/ntfy-helper.ts — Helper centralizado
• ntfy.sh docs — Documentação oficial
• ntfy.sh security — Controle de acesso