🛡️ SDK AntiFraud

Um SDK completo para detecção de fraude que coleta fingerprints do dispositivo e analisa riscos em tempo real.

📋 Funcionalidades

• Device Fingerprinting: Coleta informações únicas do dispositivo
• Behavioral Analysis: Monitora comportamento do usuário
• IP Verification: Verifica endereços IP suspeitos
• Real-time Risk Scoring: Pontuação de risco em tempo real
• Express.js Middleware: Integração fácil com Express

🚀 Instalação

npm install sdk-antifraud-core@latest

📖 Uso Básico

Importação

import {
  AdvancedVerifier,
  FingerprintCollector,
  Config,
} from "sdk-antifraud-core";

Verificação Simples de IP

import { AdvancedVerifier } from "sdk-antifraud-core";

const verifier = AdvancedVerifier.init();

// Verificar IP específico
const result = await verifier.verifyIp({ ip: "192.168.1.1" });
console.log(result);
// { status: "ALLOW" | "REVIEW" | "DENY", riskScore: 25, reasons: [...], ... }

// OU usar como middleware (pega IP automaticamente da requisição)
app.use("/api", verifier.middlewareIpOnly());

Middleware para Express

import express from "express";
import { AdvancedVerifier } from "sdk-antifraud-core";

const app = express();
const verifier = AdvancedVerifier.init();

// Middleware de verificação avançada
app.use("/login", verifier.middlewareAdvancedVerify("/login", "user123"));

// Middleware apenas para IP
app.use("/api", verifier.middlewareIpOnly());

app.post("/login", (req, res) => {
  const result = req.verificationResult;

  if (result.status === "DENY") {
    return res.status(403).json({ error: "Acesso negado" });
  }

  if (result.status === "REVIEW") {
    return res.status(202).json({ message: "Em análise" });
  }

  // ALLOW - continuar com login
  res.json({ message: "Login aprovado" });
});

Coleta Manual de Fingerprint

import { FingerprintCollector } from "sdk-antifraud-core";

const collector = new FingerprintCollector();

// Coletar fingerprint completo
const fingerprint = collector.collectCompleteFingerprint("user123");

// Coletar apenas device fingerprint
const device = collector.collectDeviceFingerprint();

// Coletar apenas behavior fingerprint
const behavior = collector.collectBehaviorFingerprint();

⚙️ Configuração

URL da API

Por padrão, o SDK usa https://sdk-antifraud.koyeb.app. Para alterar:

// Opção 1: Via parâmetro
const verifier = AdvancedVerifier.init("https://sua-api.com");

// Opção 2: Via variável de ambiente
// ANTIFRAUD_API_URL=https://sua-api.com
const verifier = AdvancedVerifier.init();

Configurações Avançadas

import { Config } from "sdk-antifraud-core";

// Usar URLs pré-configuradas
const devUrl = Config.getApiUrl("DEVELOPMENT"); // http://localhost:8080
const stagingUrl = Config.getApiUrl("STAGING"); // https://sdk-antifraud-staging.koyeb.app
const prodUrl = Config.getApiUrl("PRODUCTION"); // https://sdk-antifraud.koyeb.app

// Configurações disponíveis
console.log(Config.API_URL);
console.log(Config.TIMEOUT);

// Verificar ambiente atual
console.log(Config.isDevelopment()); // true/false
console.log(Config.isProduction()); // true/false

// Obter todas as configurações
const config = Config.getConfig();
console.log(config);

Variáveis de Ambiente

O SDK suporta as seguintes variáveis de ambiente:

# URL da API (sobrescreve configuração padrão)
ANTIFRAUD_API_URL=https://sua-api.com

# Timeout para requisições em ms (padrão: 10000)
ANTIFRAUD_TIMEOUT=15000

# Ambiente de execução
NODE_ENV=production

🎯 Filosofia do SDK

O SDK é neutro e flexível - ele apenas coleta dados e fornece informações. VOCÊ decide as regras de negócio:

• ✅ SDK coleta: Fingerprints, IPs, dados de comportamento
• ✅ SDK fornece: Status, score de risco, motivos
• ✅ VOCÊ decide: O que fazer com cada resposta
• ✅ VOCÊ cria: Suas próprias regras de negócio

Exemplo de Flexibilidade

// Mesma resposta, regras diferentes:
const { status, riskScore } = req.verificationResult!;

// E-commerce: Negar se DENY
if (status === "DENY") res.status(403).json({ error: "Negado" });

// Banking: Sempre permitir, mas logar
if (status === "DENY") console.log("Alto risco detectado:", riskScore);

// Gaming: Apenas alertar
if (riskScore > 80) res.json({ warning: "Conta suspeita" });

📊 Tipos de Resposta

interface VerificationResponse {
  status: "ALLOW" | "REVIEW" | "DENY";
  riskScore: number; // 0-100
  reasons: string[]; // Motivos da decisão
  sessionId: string; // ID da sessão
  timestamp: number; // Timestamp Unix
}

Status de Verificação

• ALLOW: Aprovado - baixo risco
• REVIEW: Em análise - risco médio
• DENY: Negado - alto risco

🔧 Exemplos Avançados

🛒 E-commerce - Regras Rígidas

// Checkout com regras rígidas de segurança
app.post(
  "/checkout",
  verifier.middlewareAdvancedVerify("/checkout"),
  (req, res) => {
    const { status, riskScore, reasons } = req.verificationResult!;

    // Regras rígidas para e-commerce
    if (status === "DENY") {
      return res.status(403).json({ error: "Transação bloqueada", reasons });
    }

    if (riskScore > 70) {
      return res.status(202).json({
        message: "Verificação adicional necessária",
        requiresAuth: true,
      });
    }

    // Processar pagamento
    res.json({ success: true, orderId: generateOrderId() });
  }
);

🏦 Banking - Regras Flexíveis

// Banking com regras mais flexíveis
app.post(
  "/transfer",
  verifier.middlewareAdvancedVerify("/transfer"),
  (req, res) => {
    const { status, riskScore, reasons } = req.verificationResult!;

    // Banking: Sempre permitir, mas com controles
    if (status === "DENY") {
      // Log para auditoria, mas permite
      auditLog("Alto risco detectado", { riskScore, reasons });
    }

    if (riskScore > 80) {
      // Requer aprovação manual
      return res.json({
        status: "pending_approval",
        message: "Transferência em análise",
      });
    }

    // Processar transferência
    res.json({ success: true });
  }
);

🎮 Gaming - Regras Personalizadas

// Gaming com regras específicas
app.post(
  "/purchase-credits",
  verifier.middlewareAdvancedVerify("/credits"),
  (req, res) => {
    const { status, riskScore } = req.verificationResult!;

    // Gaming: Apenas alertar, não bloquear
    if (riskScore > 60) {
      return res.json({
        warning: "Conta suspeita detectada",
        requiresPhoneVerification: true,
      });
    }

    // Processar compra
    res.json({ success: true, credits: req.body.amount });
  }
);

🔐 Login - Verificação de IP

// Login com verificação de IP
app.post("/login", verifier.middlewareIpOnly(), (req, res) => {
  const { status, riskScore } = req.verificationResult!;

  // IP suspeito - solicitar 2FA
  if (riskScore > 70) {
    return res.json({
      requires2FA: true,
      message: "Verificação adicional necessária",
    });
  }

  // IP confiável - login normal
  res.json({
    success: true,
    token: generateToken(),
    riskLevel: riskScore < 30 ? "low" : "medium",
  });
});

React/Next.js Integration

// hooks/useAntiFraud.ts
import { FingerprintCollector } from "sdk-antifraud-core";

export const useAntiFraud = () => {
  const [collector] = useState(() => new FingerprintCollector());

  const getFingerprint = useCallback(() => {
    return collector.collectCompleteFingerprint();
  }, [collector]);

  return { getFingerprint };
};

// Component
const LoginForm = () => {
  const { getFingerprint } = useAntiFraud();

  const handleSubmit = async (data) => {
    const fingerprint = getFingerprint();

    const response = await fetch("/api/login", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        ...data,
        fingerprint,
      }),
    });
  };
};

🌐 API Endpoints

O SDK se conecta com estes endpoints:

• POST /verify-ip - Verificação de IP
• POST /verify-fingerprint - Verificação avançada
• GET / - Status da API
• GET /actuator/health - Health check

🔒 Segurança

• HTTPS: Sempre use HTTPS em produção
• Rate Limiting: Implemente rate limiting no servidor
• Logs: Monitore tentativas suspeitas
• Dados: Fingerprints não são armazenados permanentemente
• Fallback Seguro: Em caso de erro na API, o SDK retorna status "REVIEW" para análise manual
• Headers: SDK inclui User-Agent identificador para auditoria

🐛 Troubleshooting

Teste de Conectividade

import { AdvancedVerifier } from "sdk-antifraud-core";

const verifier = AdvancedVerifier.init();

// Testar conexão com a API
const connectionTest = await verifier.testApiConnection();
console.log(connectionTest.status); // "success" ou "error"
console.log(connectionTest.message);

// Obter informações da API
const apiInfo = await verifier.getApiInfo();
console.log(apiInfo);
/* Exemplo de resposta:
{
  "service": "SDK Anti-Fraud API",
  "version": "1.0.0",
  "status": "UP",
  "endpoints": [
    "/verify-ip - Verificação de IP",
    "/verify-fingerprint - Verificação avançada de fingerprint"
  ]
}
*/

Erro de Conexão

// O SDK agora retorna respostas seguras em caso de erro
// Em vez de lançar exceções, retorna status "REVIEW" com riskScore 100
const result = await verifier.verifyIp({ ip: "192.168.1.1" });
if (result.reasons.includes("Erro na comunicação com a API")) {
  console.log("API indisponível, usando fallback seguro");
}

Timeout

// Configurar timeout via variável de ambiente
// ANTIFRAUD_TIMEOUT=15000

// Ou usar Config
import { Config } from "sdk-antifraud-core";
console.log("Timeout atual:", Config.TIMEOUT);

Browser Compatibility

O SDK funciona em todos os navegadores modernos. Para navegadores antigos, alguns recursos podem não estar disponíveis.

📚 Tipos TypeScript

// Principais interfaces
interface DeviceFingerprint {
  userAgent: string;
  language: string;
  platform: string;
  screenResolution: string;
  timezone: string;
  // ... outros campos
}

interface BehaviorFingerprint {
  mouseMovements: number;
  keystrokes: number;
  scrollEvents: number;
  // ... outros campos
}

interface NetworkFingerprint {
  ip: string;
  connectionType?: string;
  effectiveType?: string;
  // ... outros campos
}

🤝 Contribuição

1. Fork o projeto
2. Crie uma branch: git checkout -b feature/nova-funcionalidade
3. Commit: git commit -m 'Add nova funcionalidade'
4. Push: git push origin feature/nova-funcionalidade
5. Abra um Pull Request

📄 Licença

MIT License - veja o arquivo LICENSE para detalhes.

🔗 Links

• API: https://sdk-antifraud.koyeb.app
• Swagger: https://sdk-antifraud.koyeb.app/swagger-ui.html
• NPM: https://www.npmjs.com/package/sdk-antifraud-core
• GitHub: https://github.com/luccastk/SDK-AntiFraud

Desenvolvido com ❤️ para proteger aplicações web