Integração ponta a ponta

// unifokal.ts -> roda no SEU SERVIDOR. Nunca importe este arquivo em codigo de navegador:
// a chave secreta mora aqui, e no navegador ela ficaria visivel para qualquer visitante,
// que passaria a abrir sessoes na sua conta com voce pagando por elas.
const API = "https://api.unifokal.com/v1";

const SECRET_KEY = process.env.UNIFOKAL_SECRET_KEY;
if (!SECRET_KEY) throw new Error("Defina UNIFOKAL_SECRET_KEY no ambiente do servidor.");

export class UnifokalError extends Error {
  constructor(readonly status: number, readonly code: string, message: string) {
    super(message);
    this.name = "UnifokalError";
  }
}

export interface SessaoCriada {
  id: string; // vs_... -> o UNICO valor que pode ir ao navegador
  expiresIn: number; // segundos de vida da sessao (900 = 15 min)
  modules: string[]; // modulos do flow, na ordem
  livemode: boolean; // false em sandbox
}

export async function criarSessao(entrada: {
  flowId: string;
  /**
   * OBRIGATORIO, e ele e a chave de idempotencia do NOSSO lado: repetir a chamada com o mesmo
   * reference_id devolve a MESMA sessao enquanto ela viver, em vez de criar (e cobrar) outra. Nao
   * existe header de idempotencia nesta rota.
   *
   * NAO existe campo de e-mail nem de telefone: o contato do titular e sempre digitado no widget,
   * que tambem dispara o codigo. Mandar qualquer um dos dois e 422 (email_not_accepted /
   * phone_not_accepted).
   */
  referenceId: string;
}): Promise<SessaoCriada> {
  const corpo: Record<string, unknown> = {
    flow_id: entrada.flowId,
    reference_id: entrada.referenceId,
  };

  const resp = await fetch(`${API}/verification-sessions`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(corpo),
    signal: AbortSignal.timeout(15_000),
  });

  // Le como TEXTO primeiro: um 502 do seu proxy volta em HTML, e resp.json() lancaria
  // um erro de parse que esconde o status real.
  const bruto = await resp.text();
  let dados: Record<string, unknown> = {};
  try {
    dados = bruto ? (JSON.parse(bruto) as Record<string, unknown>) : {};
  } catch {
    /* resposta nao-JSON: seguimos com o status, que e a informacao que importa */
  }

  if (!resp.ok) {
    const code = typeof dados.error === "string" ? dados.error : "unknown_error";
    const message = typeof dados.message === "string" ? dados.message : bruto.slice(0, 200);
    throw new UnifokalError(resp.status, code, message);
  }

  return {
    id: String(dados.id),
    expiresIn: Number(dados.expires_in),
    modules: Array.isArray(dados.modules) ? (dados.modules as string[]) : [],
    livemode: dados.livemode === true,
  };
}

// O QUE ESPERAR DE VOLTA: em sucesso, o objeto acima com "id" comecando em vs_ e expiresIn = 900.
// Em falha, um UnifokalError com o codigo estavel em .code. Trate ao menos estes tres, que sao os
// que mudam o que voce mostra ao usuario:
//
//   try {
//     const sessao = await criarSessao({ flowId, referenceId: usuario.id });
//   } catch (err) {
//     if (err instanceof UnifokalError && err.code === "insufficient_credit") {
//       // sua conta ficou sem saldo: avise o time, e mostre "tente em instantes" ao usuario
//     } else if (err instanceof UnifokalError && err.code === "rate_limited") {
//       // espere e repita: e teto por minuto, some sozinho
//     } else if (err instanceof UnifokalError && err.code === "flow_not_found") {
//       // configuracao errada (flow de outro ambiente): repetir NAO resolve
//     } else if (err instanceof UnifokalError && err.code === "email_not_accepted") {
//       // voce mandou "email" no corpo: tire. O widget pergunta o endereco ao titular. Repetir
//       // com o campo NAO resolve, e nenhuma sessao foi criada nem cobrada.
//     }
//     throw err;
//   }

# unifokal.py -> roda no SEU SERVIDOR. A chave secreta mora aqui, em variavel de ambiente.
# Nunca a mande ao navegador: la ela fica visivel para qualquer visitante, que passaria a abrir
# sessoes na sua conta com voce pagando por elas.
#
# So biblioteca padrao: nada para instalar.
import json
import os
import urllib.error
import urllib.request

API = "https://api.unifokal.com/v1"
SECRET_KEY = os.environ["UNIFOKAL_SECRET_KEY"]  # sk_live_... ou sk_test_...


class UnifokalError(Exception):
    def __init__(self, status: int, code: str, message: str) -> None:
        super().__init__(f"{status} {code}: {message}")
        self.status = status
        self.code = code


def criar_sessao(
    flow_id: str,
    reference_id: str,
) -> dict:
    """Cria a sessao e devolve o corpo 201 inteiro.

    reference_id: OBRIGATORIO, e e a chave de idempotencia do NOSSO lado. Se o seu
    processo re-executar, o mesmo reference_id devolve a MESMA sessao em vez de criar
    (e cobrar) outra. Nao existe header de idempotencia nesta rota.

    Nao existe parametro de e-mail nem de telefone: o contato do titular e sempre
    digitado no widget, que tambem dispara o codigo. Mandar qualquer um dos dois no
    corpo e 422 (email_not_accepted / phone_not_accepted).
    """
    corpo = {"flow_id": flow_id, "reference_id": reference_id}

    req = urllib.request.Request(
        f"{API}/verification-sessions",
        method="POST",
        data=json.dumps(corpo).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {SECRET_KEY}",
            "Content-Type": "application/json",
        },
    )

    try:
        with urllib.request.urlopen(req, timeout=15) as resp:
            return json.loads(resp.read().decode("utf-8"))
    except urllib.error.HTTPError as err:
        bruto = err.read().decode("utf-8", "replace")
        try:
            dados = json.loads(bruto)
        except ValueError:
            dados = {}  # 502 do seu proxy volta em HTML: fique com o status, que e o que importa
        raise UnifokalError(
            err.code,
            dados.get("error", "unknown_error"),
            dados.get("message", bruto[:200]),
        ) from err


# O QUE ESPERAR DE VOLTA: em sucesso, o dicionario 201 com "id" comecando em vs_ e "expires_in" = 900.
# Em falha, um UnifokalError com o codigo estavel em .code. Os tres que mudam o que voce mostra:
#
#     try:
#         sessao = criar_sessao(FLOW_ID, reference_id=usuario.id)
#     except UnifokalError as err:
#         if err.code == "insufficient_credit":
#             ...  # conta sem saldo: avise o time, mostre "tente em instantes" ao usuario
#         elif err.code == "rate_limited":
#             ...  # teto por minuto: espere e repita
#         elif err.code == "flow_not_found":
#             ...  # flow de outro ambiente: repetir NAO resolve, e configuracao
#         raise

// A rota que RENDERIZA a pagina. Ela roda NO SEU SERVIDOR: e la que a chave secreta vive, e e
// de la que ela nunca sai. Ao navegador vai SO o id da sessao. E a fronteira inteira do produto
// num arquivo: de um lado a chave, do outro o id descartavel.
import express from "express";
import { criarSessao } from "./unifokal";

const app = express();

app.get("/verificacao", async (req, res, next) => {
  try {
    const usuario = req.user; // o seu usuario ja autenticado no SEU sistema

    // O `reference_id` e a chave de idempotencia, e voce nao precisa gerenciar nada: a nossa
    // selagem dura o que a SESSAO dura (15 minutos), nao 24h. Enquanto a
    // sessao esta viva, repetir esta chamada devolve ela mesma (recarregar a pagina reusa a sessao,
    // e um retry de rede nao cria nem cobra uma segunda). Quando ela vence, o MESMO `reference_id`
    // abre uma sessao nova, que e o que o titular precisa para tentar de novo.
    const sessao = await criarSessao({
      flowId: process.env.UNIFOKAL_FLOW_ID!,
      referenceId: usuario.id,
    });

    // A pagina que monta a camera precisa DESTES cabecalhos. Sem eles o widget carrega
    // e trava sem mensagem, porque o bloqueio acontece no browser, nao na nossa API.
    //
    // O nonce e por REQUISICAO, nunca fixo: um nonce constante e o mesmo que 'unsafe-inline',
    // so que com mais passos. Ele autoriza o UNICO script inline desta pagina, o que chama
    // IdSaas.mount. Sem ele, o bundle carrega, o mount nao roda, e o seu usuario ve uma area
    // em branco no meio do cadastro, sem erro nenhum na tela.
    const nonce = crypto.randomUUID();
    res.setHeader(
      "Content-Security-Policy",
      [
        "default-src 'self'",
        // o bundle do widget e servido pela nossa origem; o nonce libera o mount inline
        `script-src 'self' https://api.unifokal.com 'nonce-${nonce}'`,
        // REST + o canal de tempo real (wss) do widget
        "connect-src 'self' https://api.unifokal.com wss://api.unifokal.com",
        // o detector de rosto roda num worker de blob:, e os frames viram blob:/data:
        "worker-src 'self' blob:",
        "img-src 'self' data: blob:",
        "style-src 'self' 'unsafe-inline'",
      ].join("; "),
    );
    // A camera roda NO SEU DOCUMENTO. Se a sua pagina manda camera=(), o widget nao
    // consegue abrir a camera e o usuario fica preso na primeira tela.
    res.setHeader("Permissions-Policy", "camera=(self), microphone=()");

    res.send(`<!doctype html>
<html lang="pt-BR">
  <head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /></head>
  <body>
    <div id="identidade"></div>

    <!-- Aqui NAO existe segredo nenhum. O unico valor que chega ao navegador e o id da
         sessao (vs_...), que so serve para ESTA verificacao e vence em 15 minutos.
         A sua chave sk_ ficou no servidor, na chamada acima. -->
    <script src="https://api.unifokal.com/dist/widget.global.js" crossorigin="anonymous"></script>
    <script nonce="${nonce}">
      IdSaas.mount({ sessionId: ${JSON.stringify(sessao.id)}, container: "#identidade" });

      // SINAL DE UI, e so isso. O widget avisa a sua pagina quando o titular termina:
      // "unifokal:state" a cada transicao e "unifokal:done" no fim. O detalhe traz
      // { event, state, outcome } e NADA MAIS: sem sessionId, sem PII, sem resultado de modulo.
      // Use para fechar a tela, tirar o spinner, navegar. NUNCA para liberar cadastro:
      // isto roda no navegador do titular, e o que roda la ele consegue forjar.
      window.addEventListener("unifokal:done", function (evento) {
        // outcome: "approved" | "pending" | "declined" | "failed" | "expired" | "analysis_incomplete"
        mostrarTelaDeEspera(evento.detail.outcome); // o desfecho OFICIAL vem do webhook
      });
    </script>
  </body>
</html>`);
  } catch (err) {
    next(err);
  }
});

// O QUE ESPERAR DE VOLTA: o widget desenha dentro de #identidade, conduz o usuario ate o fim e dispara
// "unifokal:done" no navegador quando terminar.
//
// O QUE NAO EXISTE, e e de proposito: rota de consulta do resultado com a sk_. O desfecho
// OFICIAL chega ao SEU BACKEND pelo webhook, voce grava, e o seu front pergunta ao SEU backend.
// O evento acima e best-effort: quem controla a pagina consegue FORJAR um "unifokal:done" com
// outcome "approved" e nada nele prova coisa alguma. Quem credita, libera ou aprova a partir dele
// esta confiando no navegador do proprio titular. Ele serve para a TELA, e so.

// webhook.ts -> o endpoint que recebe o resultado. Este e o arquivo que decide se um
// estranho consegue aprovar quem quiser no seu sistema, entao ele valida ANTES de ler o corpo.
import crypto from "node:crypto";
import express from "express";

const SIGNING_SECRET = process.env.UNIFOKAL_WEBHOOK_SECRET;
if (!SIGNING_SECRET || SIGNING_SECRET.length < 32) {
  // O segredo e ESCOLHIDO POR VOCE quando cadastra o destino no painel, e tem no minimo
  // 32 caracteres. Use "openssl rand -hex 32". Segredo curto se
  // quebra fora do ar, sem passar por nos, e quem o quebra passa a forjar aprovacoes.
  throw new Error("UNIFOKAL_WEBHOOK_SECRET ausente ou curto demais.");
}

const JANELA_SEGUNDOS = 300;

interface Assinatura {
  t: number;
  v1s: string[];
}

/**
 * O header vem como "t=<epoch>,v1=<hex>" e pode trazer MAIS DE UM v1 ("t=...,v1=A,v1=B").
 * E assim que a troca de segredo acontece sem derrubar entrega. Um parse que devolva so o
 * primeiro (Object.fromEntries, por exemplo) faz o seu endpoint RECUSAR entregas legitimas
 * durante toda a janela de rotacao, e o sintoma aparece dias depois.
 */
function parseAssinatura(header: string | undefined): Assinatura | null {
  if (!header) return null;
  let t: number | null = null;
  const v1s: string[] = [];
  for (const par of header.split(",")) {
    const i = par.indexOf("=");
    if (i < 0) continue;
    const chave = par.slice(0, i).trim();
    const valor = par.slice(i + 1).trim();
    if (chave === "t") t = Number(valor);
    else if (chave === "v1" && valor) v1s.push(valor);
  }
  if (t === null || !Number.isFinite(t) || v1s.length === 0) return null;
  return { t, v1s };
}

/**
 * Comparacao em TEMPO CONSTANTE. Dois cuidados que separam "compara" de "compara de verdade":
 *   1. "===" sai no primeiro byte diferente e vira um oraculo: o atacante mede o tempo e
 *      descobre a assinatura byte a byte, sem nunca saber o segredo;
 *   2. timingSafeEqual LANCA quando os buffers tem tamanhos diferentes, e o candidato vem do
 *      header, ou seja, de fora. Uma assinatura curta forjada viraria excecao e 500 no seu
 *      servidor. Passar os dois lados por um sha256 iguala o tamanho (sempre 32 bytes) sem
 *      abrir mao do tempo constante.
 */
function iguaisEmTempoConstante(a: string, b: string): boolean {
  const ha = crypto.createHash("sha256").update(a).digest();
  const hb = crypto.createHash("sha256").update(b).digest();
  return crypto.timingSafeEqual(ha, hb);
}

const app = express();

app.post(
  "/webhooks/unifokal",
  // express.raw, NAO express.json: a assinatura cobre os BYTES CRUS recebidos. Reserializar o
  // JSON muda um espaco ou a ordem de uma chave e derruba toda validacao, sem erro visivel.
  express.raw({ type: "application/json", limit: "1mb" }),
  async (req, res) => {
    const corpoCru = req.body as Buffer;
    const assinatura = parseAssinatura(req.header("X-IDSAAS-Signature") ?? undefined);
    if (!assinatura) return res.status(400).json({ error: "assinatura ausente ou malformada" });

    // Janela anti-replay: rejeita um corpo CAPTURADO e re-postado depois. Isto nao conflita com
    // as nossas retentativas: cada tentativa (inclusive replay e reemissao pelo painel) e
    // assinada NA HORA DO ENVIO, com t novo, entao retry legitimo sempre passa aqui.
    const agora = Math.floor(Date.now() / 1000);
    if (Math.abs(agora - assinatura.t) > JANELA_SEGUNDOS) {
      return res.status(400).json({ error: "assinatura fora da janela" });
    }

    const esperado = crypto
      .createHmac("sha256", SIGNING_SECRET)
      .update(`${assinatura.t}.${corpoCru.toString("utf8")}`)
      .digest("hex");

    // Aceita se QUALQUER v1 casar: e o que sustenta a janela de rotacao de segredo.
    if (!assinatura.v1s.some((v1) => iguaisEmTempoConstante(v1, esperado))) {
      return res.status(400).json({ error: "assinatura invalida" });
    }

    // So DEPOIS de validar o corpo vira dado.
    const evento = JSON.parse(corpoCru.toString("utf8"));

    // Entrega e pelo menos UMA vez: retentativa, replay e reemissao manual trazem o mesmo
    // resultado de novo. Deduplique pelo id do evento (estavel por verificacao e por tipo).
    if (await jaProcessamos(evento.id)) return res.status(200).end();

    // Responda rapido e processe fora do ciclo: se voce demorar, nos re-tentamos e voce
    // recebe o mesmo evento outra vez enquanto ainda esta processando o primeiro.
    await enfileirar(evento);
    return res.status(200).end();
  },
);

// O QUE ESPERAR DE VOLTA: 200 em toda entrega legitima, 400 no que voce recusar. Do nosso lado, 2xx encerra o
// ciclo; timeout, erro de rede e 5xx viram retentativa (ate 3); 4xx e lido como recusa definitiva
// daquele destino, entao nao devolva 4xx por erro transitorio do seu banco: devolva 5xx e receba de novo.
//
// O nosso limite de espera pela SUA resposta e de 5 segundos: estourou, abortamos
// a conexao e a entrega vira retentativa: voce recebe o mesmo evento de novo, com o mesmo id. E por
// isso que o handler acima grava e enfileira em vez de processar dentro do ciclo.

# webhook.py -> o endpoint que recebe o resultado. Este e o arquivo que decide se um estranho
# consegue aprovar quem quiser no seu sistema, entao ele valida ANTES de ler o corpo.
#
# Framework a gosto: o que importa e (1) pegar os BYTES CRUS e (2) comparar em tempo constante.
import hashlib
import hmac
import json
import os
import time

from flask import Flask, request

SIGNING_SECRET = os.environ["UNIFOKAL_WEBHOOK_SECRET"].encode("utf-8")
if len(SIGNING_SECRET) < 32:
    # O segredo e ESCOLHIDO POR VOCE ao cadastrar o destino no painel, com no minimo
    # 32 caracteres ("openssl rand -hex 32"). Segredo curto se quebra
    # fora do ar, sem passar por nos, e quem o quebra passa a forjar aprovacoes assinadas.
    raise RuntimeError("UNIFOKAL_WEBHOOK_SECRET curto demais.")

JANELA_SEGUNDOS = 300

app = Flask(__name__)


def parse_assinatura(header: str | None) -> tuple[int, list[str]] | None:
    """Le "t=<epoch>,v1=<hex>". O header pode trazer MAIS DE UM v1 ("t=...,v1=A,v1=B"):
    e assim que a troca de segredo acontece sem derrubar entrega. Um parse que fique so com
    o primeiro (dict(par.split("=")) por exemplo) faz o seu endpoint RECUSAR entregas
    legitimas durante toda a janela de rotacao, e o sintoma aparece dias depois.
    """
    if not header:
        return None
    t = None
    v1s = []
    for par in header.split(","):
        chave, _, valor = par.partition("=")
        chave, valor = chave.strip(), valor.strip()
        if chave == "t":
            try:
                t = int(valor)
            except ValueError:
                return None
        elif chave == "v1" and valor:
            v1s.append(valor)
    if t is None or not v1s:
        return None
    return t, v1s


@app.post("/webhooks/unifokal")
def receber():
    # get_data() devolve os BYTES CRUS. Nao use request.json aqui: a assinatura cobre os bytes
    # recebidos, e reserializar o JSON muda um espaco ou a ordem de uma chave e derruba tudo.
    corpo_cru = request.get_data()
    lido = parse_assinatura(request.headers.get("X-IDSAAS-Signature"))
    if lido is None:
        return {"error": "assinatura ausente ou malformada"}, 400
    t, v1s = lido

    # Janela anti-replay: rejeita um corpo CAPTURADO e re-postado depois. Nao conflita com as
    # nossas retentativas: cada tentativa (inclusive replay e reemissao pelo painel) e assinada
    # na hora do envio, com t novo, entao retry legitimo sempre passa aqui.
    if abs(int(time.time()) - t) > JANELA_SEGUNDOS:
        return {"error": "assinatura fora da janela"}, 400

    esperado = hmac.new(
        SIGNING_SECRET,
        f"{t}.".encode("utf-8") + corpo_cru,
        hashlib.sha256,
    ).hexdigest()

    # hmac.compare_digest e a comparacao em TEMPO CONSTANTE da biblioteca padrao. Nunca use "==":
    # ele sai no primeiro byte diferente e vira um oraculo, e o atacante descobre a assinatura
    # byte a byte sem nunca saber o segredo. Aceita se QUALQUER v1 casar (janela de rotacao).
    if not any(hmac.compare_digest(v1, esperado) for v1 in v1s):
        return {"error": "assinatura invalida"}, 400

    # So DEPOIS de validar o corpo vira dado.
    evento = json.loads(corpo_cru)

    # Entrega e pelo menos UMA vez: retentativa, replay e reemissao manual trazem o mesmo
    # resultado de novo. Deduplique pelo id do evento (estavel por verificacao e por tipo).
    if ja_processamos(evento["id"]):
        return "", 200

    # Responda rapido e processe fora do ciclo: se voce demorar, nos re-tentamos e voce recebe
    # o mesmo evento outra vez enquanto ainda esta processando o primeiro.
    enfileirar(evento)
    return "", 200


# O QUE ESPERAR DE VOLTA: 200 em toda entrega legitima, 400 no que voce recusar. Do nosso lado, 2xx encerra o
# ciclo; timeout, erro de rede e 5xx viram retentativa (ate 3); 4xx e lido como recusa definitiva
# daquele destino, entao nao devolva 4xx por erro transitorio do seu banco: devolva 5xx e receba de novo.
#
# O nosso limite de espera pela SUA resposta e de 5 segundos: estourou, abortamos
# a conexao e a entrega vira retentativa: voce recebe o mesmo evento de novo, com o mesmo id. E por
# isso que o handler acima grava e enfileira em vez de processar dentro do ciclo.

#!/bin/sh
# Confere, na sua maquina, se o segredo cadastrado e o mesmo que assinou a entrega. E o teste
# que responde "e o meu segredo que esta errado, ou o meu codigo?" em trinta segundos.
#
# Salve os BYTES CRUS do corpo recebido em um arquivo. Nao passe o JSON por um formatador:
# a assinatura cobre os bytes, e um espaco a mais ja derruba a conferencia.

CORPO_ARQUIVO="corpo-recebido.json"

# O valor do header X-IDSAAS-Signature da entrega, colado como veio. Ele pode trazer MAIS DE UM
# v1 ("t=...,v1=A,v1=B"): e assim que a rotacao de segredo acontece sem derrubar entrega, e o
# laco abaixo aceita se QUALQUER um casar.
HEADER='t=1756143600,v1=6f0c9a1d2b3e4f50617283940a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7'
SEGREDO="$UNIFOKAL_WEBHOOK_SECRET"

T=$(printf '%s' "$HEADER" | tr ',' '\n' | sed -n 's/^t=//p')

# O material assinado e "<t>.<corpo cru>". O "cat" preserva os bytes exatos, inclusive a
# ultima quebra de linha, que um "printf" com variavel de shell comeria.
ESPERADO=$({ printf '%s.' "$T"; cat "$CORPO_ARQUIVO"; } \
  | openssl dgst -sha256 -hmac "$SEGREDO" -r | cut -d' ' -f1)

# Comparacao em TEMPO CONSTANTE sem primitiva de tempo constante no shell: aplique um HMAC com
# uma chave EFEMERA nos dois lados e compare os digests. O "=" do shell continua saindo no
# primeiro byte diferente, mas agora ele compara digests sob uma chave que o atacante nao
# conhece, entao o tempo nao ensina nada sobre a assinatura. E a mesma defesa que hmac.compare_digest
# e crypto.timingSafeEqual dao de graca nas outras duas formas: aqui ela e explicita.
CHAVE=$(openssl rand -hex 32)
mascara() { printf '%s' "$1" | openssl dgst -sha256 -hmac "$CHAVE" -r | cut -d' ' -f1; }

ALVO=$(mascara "$ESPERADO")
for V1 in $(printf '%s' "$HEADER" | tr ',' '\n' | sed -n 's/^v1=//p'); do
  if [ "$(mascara "$V1")" = "$ALVO" ]; then
    echo "assinatura confere"
    exit 0
  fi
done

echo "assinatura NAO confere"
exit 1

# O QUE ESPERAR DE VOLTA: "assinatura confere" e saida 0 quando o segredo do ambiente e o mesmo que
# cadastrou no painel. "assinatura NAO confere" aponta para uma destas tres causas, nesta
# ordem de frequencia: segredo do ambiente errado, corpo reformatado, ou o "t" do header
# trocado pelo horario de agora.
#
# Isto e DIAGNOSTICO. Em producao a validacao roda no seu servidor, nas formas acima.

// Os sete valores de status sao o contrato inteiro. Trate os sete: um "default" que aprova
// e a forma mais rapida de transformar uma recusa nossa num cadastro liberado no seu sistema.
type Status = "approved" | "denied" | "pending" | "blocked" | "failed" | "review" | "consent_declined";

export async function aplicarDesfecho(evento: {
  event: string; // "verification.completed" | "verification.blocked" | ...
  data: {
    verification_id: string;
    reference_id: string | null;
    status: Status;
    score: number | null;
    risk_level: "low" | "medium" | "high" | null;
    recommendation: "approve" | "review" | "decline" | null;
    reason_code?: unknown;
  };
}): Promise<void> {
  const { status, reference_id: referenceId, verification_id: verificationId } = evento.data;

  switch (status) {
    case "approved":
      // Identidade comprovada. Libere o que depende dela.
      await liberarCadastro(referenceId, verificationId);
      return;

    case "denied":
      // Reprovou em um portao (biometria, documento, coerencia). Nao libere.
      await recusarCadastro(referenceId, verificationId);
      return;

    case "review":
      // Nem aprovado nem reprovado: alguem seu precisa olhar. E o desfecho que existe
      // justamente para nao aprovar no automatico o que pede julgamento humano.
      await enviarParaAnaliseHumana(referenceId, verificationId);
      return;

    case "blocked":
      // O documento (ou um socio) esta na SUA lista de bloqueio. Nao e cobrado.
      await recusarCadastro(referenceId, verificationId);
      return;

    case "pending":
      // Ainda processando, ou uma fonte externa nao respondeu. NAO e um desfecho final:
      // nao libere e nao recuse, aguarde o proximo evento da mesma verificacao.
      return;

    case "failed":
      // Erro do nosso lado. Nao e cobrado, e o usuario pode refazer.
      await pedirNovaTentativa(referenceId);
      return;

    case "consent_declined":
      // O titular optou por nao continuar na tela de consentimento. NAO e reprovacao: nao
      // recuse o cadastro. Nao e cobrado. Se ele reconsiderar, uma verificacao NOVA chega
      // num proximo evento.
      return;
  }
}

// "recommendation" (approve | review | decline) e a nossa sugestao, e "risk_level"
// (low | medium | high) e a leitura de risco. Os dois existem para voce apertar a sua regra
// alem da nossa: por exemplo, mandar para analise humana todo approved com risk_level "high"
// acima de um certo valor de transacao. O que voce NAO deve fazer e ler so o score: ele e um
// numero comparavel dentro de uma politica, e a politica pode mudar.

// O QUE ESPERAR DE VOLTA: cada verificacao chega uma vez em um desfecho final (approved, denied, review,
// blocked, failed ou consent_declined). "pending" pode chegar antes, e nao substitui o final.
// Como a entrega e pelo menos uma vez, escreva este trecho como upsert por verification_id:
// rodar duas vezes com o mesmo evento tem que dar o mesmo resultado.

# Os sete valores de status sao o contrato inteiro. Trate os sete: um "else" que aprova e a
# forma mais rapida de transformar uma recusa nossa num cadastro liberado no seu sistema.
def aplicar_desfecho(evento: dict) -> None:
    dados = evento["data"]
    status = dados["status"]
    reference_id = dados.get("reference_id")
    verification_id = dados["verification_id"]

    if status == "approved":
        # Identidade comprovada. Libere o que depende dela.
        liberar_cadastro(reference_id, verification_id)

    elif status == "denied":
        # Reprovou em um portao (biometria, documento, coerencia). Nao libere.
        recusar_cadastro(reference_id, verification_id)

    elif status == "review":
        # Nem aprovado nem reprovado: alguem seu precisa olhar. E o desfecho que existe
        # justamente para nao aprovar no automatico o que pede julgamento humano.
        enviar_para_analise_humana(reference_id, verification_id)

    elif status == "blocked":
        # O documento (ou um socio) esta na SUA lista de bloqueio. Nao e cobrado.
        recusar_cadastro(reference_id, verification_id)

    elif status == "pending":
        # Ainda processando, ou uma fonte externa nao respondeu. NAO e desfecho final:
        # nao libere e nao recuse, aguarde o proximo evento da mesma verificacao.
        return

    elif status == "failed":
        # Erro do nosso lado. Nao e cobrado, e o usuario pode refazer.
        pedir_nova_tentativa(reference_id)

    elif status == "consent_declined":
        # O titular optou por nao continuar na tela de consentimento. NAO e reprovacao: nao
        # recuse o cadastro. Nao e cobrado. Se ele reconsiderar, uma verificacao NOVA chega
        # num proximo evento.
        return

    else:
        # Status desconhecido: a politica publicada permite VALOR NOVO em enum de saida sem
        # trocar a versao. Registre e segure, nunca aprove por omissao.
        registrar_status_desconhecido(verification_id, status)


# "recommendation" (approve | review | decline) e a nossa sugestao, e "risk_level"
# (low | medium | high) e a leitura de risco. Os dois existem para voce apertar a sua regra alem
# da nossa: por exemplo, mandar para analise humana todo approved com risk_level "high" acima de
# um certo valor de transacao. O que voce NAO deve fazer e ler so o score: ele e um numero
# comparavel dentro de uma politica, e a politica pode mudar.

# O QUE ESPERAR DE VOLTA: cada verificacao chega uma vez em um desfecho final (approved, denied, review,
# blocked, failed ou consent_declined). "pending" pode chegar antes, e nao substitui o final.
# Como a entrega e pelo menos uma vez, escreva este trecho como upsert por verification_id:
# rodar duas vezes com o mesmo evento tem que dar o mesmo resultado.

# O seu sistema ficou fora do ar e os webhooks falharam. Nada se perde: liste o que nao foi
# entregue e redispare. Voce recebe o corpo EXATO que teria recebido, com assinatura nova.
# As respostas vao comentadas para o bloco inteiro poder ser colado no terminal.

# 1) o que ficou para tras (o teto por pagina e 20, mesmo que voce peca mais; pagine com page=2, 3, ...)
curl -sS "https://api.unifokal.com/v1/webhook-events?page=1&limit=20" \
  -H "Authorization: Bearer $UNIFOKAL_SECRET_KEY"

# O QUE ESPERAR DE VOLTA (200): uma entrada por verificacao mais evento, ja idempotente.
# {
#   "data": [
#     { "event_type": "completed",
#       "verification_id": "ver_01J8ZQ7V1X2Y3Z4A5B6C7D8E9F",
#       "reference_id": "usr_8842",
#       "target_url": "sua.api",
#       "status": "error", "status_code": null, "attempts": 3,
#       "failed_at": "2026-08-25T21:14:09.312Z" }
#   ],
#   "page": 1, "totalPages": 1, "totalItems": 1
# }

# 2) redispare em lote (minimo 1, maximo 20 ids por chamada; 30 chamadas por minuto na conta)
curl -sS -X POST https://api.unifokal.com/v1/webhook-events/replay \
  -H "Authorization: Bearer $UNIFOKAL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"verification_ids": ["ver_01J8ZQ7V1X2Y3Z4A5B6C7D8E9F"]}'

# O QUE ESPERAR DE VOLTA (200): resultado POR verificacao. Erro de um item nao derruba os demais.
# {
#   "results": [
#     { "verification_id": "ver_01J8ZQ7V1X2Y3Z4A5B6C7D8E9F", "resent": true, "http_status": 200 }
#   ],
#   "resent": 1, "failed": 0
# }

# Reenviou com sucesso? A verificacao sai da listagem de erros.
#
# O target_url que a listagem devolve e o HOST do destino: o endereco completo do seu webhook so
# aparece para quem administra os endpoints, no painel.
#
# O DESTINO e o da propria entrega (o mesmo alvo que a listagem rotula), nunca "o webhook que
# o flow aponta hoje": cada linha e a promessa de entrega a UM endereco, e redirecionar o reenvio
# marcaria como entregue uma linha que nunca chegou ao destino dela. Trocou de endpoint e o antigo
# nao existe mais? O item volta { "resent": false, "error": "target_unavailable" } e o resgate e
# reemitir pelo painel, que cria a entrega do endereco novo.
# Corpo expurgado pelo prazo de retencao (ou anterior ao carimbo de corpo): "payload_unavailable".