Fase 2 — Auth, Multi-Tenant & Admin

Design técnico para transformar Carbon Exchange de single-tenant interno em produto multi-cliente com isolamento total de dados, login JWT, provisionamento via UI admin e roteamento WhatsApp por tenant + cópia auditada para grupo admin.

1. Objetivos

• Isolamento de dados: cliente A nunca vê dados do cliente B (queries automaticamente filtram por tenant_id).
• Login JWT: usuário se autentica via email + senha; recebe access token de curta duração + refresh token revogável.
• Provisionamento centralizado: somente admin global cria tenants e usuários; sem self-register.
• WhatsApp por tenant: cada cliente tem seu grupo; admin recebe cópia de tudo.
• Reaproveitamento: webhook de ingestão (POST /carbon) continua anônimo — sensores não carregam JWT.
• Auditoria: toda mensagem WhatsApp/áudio enviada é registrada em carbon.alert_events.

2. Não-objetivos (desta fase)

• SSO/OAuth (Google, Azure AD, etc.) — postergado.
• 2FA — postergado.
• API keys de leitura por tenant (M2M) — postergado.
• Pagamento/billing por tenant — fora de escopo.
• Quotas/rate-limit por tenant — usar nginx até evidência de necessidade.

3. Estado atual (Fase 1)

Já implementado e em produção:

• Webhook POST /carbon ingere leituras → JSONL audit + PostgreSQL carbon.sensor_readings.
• Mensagem WhatsApp formatada em PT-BR, enviada para grupo único Carbon Software.
• Dashboard com filtros, mapa Leaflet, previsão Open-Meteo.
• Banco dedicado carbon; tabelas Fase 2 já criadas (tenants, users, tenant_members, auth_refresh_tokens, alert_events) e vazias.
• Backfill: 4 tenants já existem, mapeados 1-para-1 com clients.client_id existente.

4. Modelo de dados

4.1 Tabelas (já existem em carbon.*)

4.2 Decisão: tenant_id em devices e sensor_readings?

Não denormalizar agora. Cada query filtra por tenant_id via JOIN devices ↔ clients. Custo do JOIN é desprezível (centenas de devices por tenant) e mantemos uma única source-of-truth para a relação cliente↔tenant.

Se métricas mostrarem latência > 50 ms em queries de histórico, denormalizar tenant_id em sensor_readings via gatilho.

5. Papéis & permissões

Combinação de flag global (users.is_admin) + papel por tenant (tenant_members.role):

Matriz de autorização

6. Resolução de tenant na ingestão

O webhook POST /carbon permanece anônimo (sensores LoRa não fazem auth). Como atribuir a leitura ao tenant correto?

Estratégia (em ordem de precedência)

1. Se o device_id já existe em carbon.devices → tenant via devices.client_id → clients.tenant_id.
2. Se não existe e payload trouxe cliente → upsert em clients (slug = slugify(cliente)) + auto-create de tenant com mesmo slug se ainda não existir.
3. Senão → fallback default-client / tenant de "órfãos".

7. JWT — claims & ciclo

Algoritmo & segredo

HS256 com segredo em env CARBON_JWT_SECRET (mínimo 32 bytes aleatórios). Rotação documentada: gerar novo secret, deploy com ambos suportados por 2× TTL do refresh, depois remover o antigo.

Access token (curto)

{
  "iss": "carbon-exchange",
  "sub": "<user_id>",
  "email": "[email protected]",
  "is_admin": false,
  "memberships": [
    {"tenant_id": 4, "role": "client_admin"},
    {"tenant_id": 7, "role": "viewer"}
  ],
  "iat": 1731000000,
  "exp": 1731003600,
  "jti": "<uuid>"
}

TTL: 60 minutos. Inclui memberships para evitar query a cada request — mas isso significa que mudanças de papel só refletem após o refresh. Aceitável.

Refresh token (longo)

String aleatória de 64 bytes (não-JWT, opaco). Hash SHA-256 do token guardado em auth_refresh_tokens.token_hash; o cliente recebe o token original. TTL: 30 dias. Revogável via UPDATE … SET revoked_at = NOW().

Fluxo de refresh

1. Frontend detecta access expirado (401) e chama POST /auth/refresh com refresh token.
2. Backend valida hash, expiração, não-revogação.
3. Emite novo access (e opcionalmente rotaciona refresh, marcando o anterior como revogado).

Storage no frontend

localStorage para ambos os tokens (simples, suficiente para protótipo). Refator para HttpOnly cookie depois quando houver requisitos PCI/LGPD mais rígidos.

8. Endpoints de auth

Hash de senha

bcrypt com cost 12 (via passlib[bcrypt] ou bcrypt direto). Validar mínimo de 10 caracteres no register/change.

Login: rate-limit & lockout

Limite de 10 tentativas falhas em 10 min por (email, IP) → 429 com retry-after de 15 min. Implementação: tabela carbon.auth_login_attempts ou Redis (TBD; usar Postgres por simplicidade enquanto não houver Redis).

9. Fluxos de sequência

9.1 Login

9.2 Request autenticado para o dashboard de um tenant

9.3 Ingestão de sensor (anônima) + roteamento WA

10. Endpoints admin / tenant

Todos requerem Authorization: Bearer <JWT>. admin = global; client_admin = só seu tenant.

11. Filtragem por tenant nas queries

Implementação: decorator @require_auth(roles=...) que injeta g.user e g.tenant_filter.

def require_auth(roles=("admin","client_admin","viewer")):
    def deco(fn):
        @wraps(fn)
        def wrapper(*args, **kw):
            token = (request.headers.get("Authorization") or "").removeprefix("Bearer ").strip()
            try:
                claims = jwt.decode(token, CARBON_JWT_SECRET, algorithms=["HS256"])
            except jwt.PyJWTError:
                return jsonify({"ok": False, "error": "unauthorized"}), 401

            g.user_id = int(claims["sub"])
            g.is_admin = bool(claims.get("is_admin"))
            g.memberships = {m["tenant_id"]: m["role"] for m in claims.get("memberships", [])}

            if not g.is_admin and not g.memberships:
                return jsonify({"ok": False, "error": "no_tenant_access"}), 403

            # Optional: per-tenant constraint via path or query param
            tenant_id = kw.get("tenant_id") or request.args.get("tenant_id", type=int)
            if tenant_id is not None and not g.is_admin:
                role = g.memberships.get(tenant_id)
                if not role or role not in roles:
                    return jsonify({"ok": False, "error": "forbidden"}), 403
                g.current_tenant = tenant_id

            return fn(*args, **kw)
        return wrapper
    return deco

Mudanças nas queries existentes

Cada _carbon_db_* ganha um filtro implícito por tenant_id:

# antes
SELECT ... FROM carbon.sensor_readings WHERE client_id = %s

# depois (não-admin)
SELECT r.* FROM carbon.sensor_readings r
JOIN carbon.clients c ON c.client_id = r.client_id
WHERE c.tenant_id = ANY(%s)        -- ARRAY de memberships do user
  AND (%s IS NULL OR r.client_id = %s)

Para admin sem tenant_id explícito, o filtro é omitido (vê tudo).

12. Roteamento WhatsApp por tenant

O POST /carbon resolve o tenant da leitura, busca tenants.whatsapp_jid, e dispara duas mensagens:

1. Para o grupo do tenant (se whatsapp_jid presente).
2. Para o grupo admin (env CARBON_ADMIN_WHATSAPP_JID).

Cada envio gera 1 linha em carbon.alert_events com channel ∈ {whatsapp_tenant, whatsapp_admin}, target=<jid>, status ∈ {sent, failed}, reading_id, message.

Falha não-bloqueante

Se o envio para tenant ou admin falhar, o webhook ainda retorna 200 (a leitura está persistida). A falha aparece em alert_events.status='failed' e pode ser replayed pela reading_id (Phase 2.1, fora deste design).

Mudança no payload de resposta

{
  "ok": true, "saved": true,
  "forwarded": {
    "tenant": {"sent": true, "target": "[email protected]"},
    "admin":  {"sent": true, "target": "[email protected]"}
  },
  "reading": {...}, "risk": {...}
}

13. Novas telas

14. Fluxo de provisioning de cliente

1. Admin cria tenant: POST /admin/tenants com slug, name. Sem whatsapp_jid ainda.
2. Cliente envia QR a Marcelo ou similar — eventualmente o número do cliente entra no Baileys (mesma instância) ou em uma instância dedicada (Phase 3).
3. Cliente cria grupo do projeto e adiciona o número Baileys. Grupo aparece em /wa/chats.
4. Admin abre editor do tenant, escolhe o JID do grupo no dropdown (alimentado por /admin/wa-groups) e salva.
5. Admin convida primeiro client_admin: define email + senha temporária; user troca no primeiro login.
6. Sensores começam a postar: webhook resolve tenant pelo cliente ou device_id já cadastrado pelo admin.
7. Mensagens fluem: cada leitura → grupo do tenant + grupo admin.

15. Migração

15.1 Estado pré-existente

4 tenants já criados (auto-backfilled de clients): vin-cola, client-acme-florestal, client-serra-verde, default-client. users e tenant_members vazios.

15.2 Passos da migração

1. Bootstrap admin user: script scripts/bootstrap_admin.py cria 1º admin a partir de env CARBON_BOOTSTRAP_ADMIN_EMAIL/PASSWORD. Idempotente; refuse se já existir admin.
2. Deploy do código com auth opcional: feature flag CARBON_AUTH_ENFORCE=false (default). Endpoints aceitam mas não exigem JWT; queries não filtram por tenant. Permite testar login/admin UI sem quebrar dashboard atual.
3. Configurar JIDs por tenant existente: admin loga, edita cada tenant, anexa JID. Verificar que POST /carbon manda para 2 grupos.
4. Convidar primeiros usuários: criar 1 client_admin por tenant existente. Logam, validam que veem só seus dados.
5. Flip da flag: CARBON_AUTH_ENFORCE=true. A partir daqui, dashboard e endpoints retornam 401 sem JWT.
6. Cleanup: drop da DB goku_games.carbon.* (já feito a Fase 1; só confirmar).

16. Rollout (sprint plan estimado)

Total: ~12-17 dias de dev efetivo. Pode paralelizar 1-2 e 3 se houver dois devs.

17. Riscos & mitigações

18. Questões abertas

1. Email de convite: começamos só com senha temporária no Sprint 3 ou já investimos em SendGrid template no Sprint 1? decidir antes do Sprint 3
2. Múltiplas instâncias Baileys: cada tenant com sua própria sessão WhatsApp (número dedicado) ou um número compartilhado mandando para vários grupos? depende do número de tenants — single-instance OK até ~50
3. Histórico antigo: leituras existentes em sensor_readings não foram associadas a tenant via reading.tenant_id direto. JOIN funciona, mas se houver renomeação de cliente e reassociação de devices, registros antigos podem aparecer no tenant errado. Aceitar e documentar?
4. Auto-provision de tenants pelo webhook (env CARBON_AUTO_PROVISION_TENANT): liga em produção ou exige sempre admin manual? recomendo desligar em prod
5. Frontend: continuar HTML estático ou migrar para React/Next.js conforme cresce? manter HTML/Vanilla até Sprint 3 terminar

Documento gerado em 2026-05-10. Carbon Exchange Phase 2 design — versão 0.1 (draft).