displayed_sidebar: bankingApiSidebar

Requisitos de Segurança

Este documento descreve as ferramentas e componentes mínimos que sua instituição parceira precisa ter implementados para se conectar de forma segura à Banking API.

📋 Visão Geral

Para garantir uma integração segura e em conformidade com os padrões de segurança bancária, sua instituição precisa implementar três camadas fundamentais de proteção:

Backend for Frontend (BFF) - Camada intermediária entre seu frontend e nossa API
Sistema de Autenticação - Validação e gerenciamento de usuários finais
Controle de Usuários Finais - Gestão de acesso e permissões dos usuários

🏗️ Arquitetura Recomendada

┌─────────────────┐
│  Frontend       │
│  (Seu App)      │
└────────┬────────┘
         │
         │ HTTPS
         │
┌────────▼─────────────────┐
│  Backend for Frontend    │  ← OBRIGATÓRIO
│  (BFF)                   │
│  - Validação de sessão   │
│  - Rate limiting         │
│  - Logging               │
└────────┬─────────────────┘
         │
         │ mTLS + OAuth2
         │
┌────────▼─────────────────┐
│  Sistema de Autenticação │  ← OBRIGATÓRIO
│  - Validação de login    │
│  - Gerenciamento de      │
│    sessões               │
└────────┬─────────────────┘
         │
         │
┌────────▼─────────────────┐
│  Controle de Usuários    │  ← OBRIGATÓRIO
│  - Permissões            │
│  - Auditoria             │
└────────┬─────────────────┘
         │
         │ mTLS + OAuth2
         │
┌────────▼─────────────────┐
│  Banking API             │
│  (ONZ Finance)           │
└──────────────────────────┘

1️⃣ Backend for Frontend (BFF)

O que é um BFF?

O BFF é uma camada intermediária entre seu frontend e nossa API Banking. Ele atua como um proxy seguro que:

Nunca expõe credenciais ao frontend
Valida e sanitiza todas as requisições
Implementa rate limiting por usuário
Centraliza lógica de negócio relacionada à integração
Gerencia tokens OAuth2 de forma segura

Por que é obrigatório?

Segurança: Credenciais (client_id e client_secret) nunca devem estar no frontend
Compliance: Atende requisitos de segurança bancária (PCI-DSS, LGPD)
Controle: Permite monitoramento e auditoria de todas as requisições
Isolamento: Protege sua infraestrutura interna

Funcionalidades Mínimas

Seu BFF deve implementar:

✅ Autenticação de Sessão

// Exemplo: Validação de sessão do usuário final
async function validateUserSession(sessionToken: string) {
  // Validar token de sessão do seu sistema
  const user = await yourAuthService.validateSession(sessionToken);
  if (!user) {
    throw new Error('Sessão inválida');
  }
  return user;
}

✅ Gerenciamento de Tokens OAuth2

// Exemplo: Cache e renovação automática de tokens
class TokenManager {
  private token: string | null = null;
  private expiresAt: number = 0;

  async getToken(): Promise<string> {
    if (this.token && Date.now() < this.expiresAt - 5 * 60 * 1000) {
      return this.token;
    }

    // Obter token usando client_credentials
    const response = await fetch(
      'https://api.bancodigital.com/public/gw_banking/v1/auth/token',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
          grant_type: 'client_credentials',
          client_id: process.env.CLIENT_ID!,
          client_secret: process.env.CLIENT_SECRET!,
        }),
      },
    );

    const data = await response.json();
    this.token = data.access_token;
    this.expiresAt = Date.now() + data.expires_in * 1000;

    return this.token;
  }
}

✅ Proxy de Requisições

// Exemplo: Proxy seguro de requisições
app.post('/api/banking/accounts/:id/balance', async (req, res) => {
  // 1. Validar sessão do usuário
  const user = await validateUserSession(req.headers.authorization);

  // 2. Obter token OAuth2
  const token = await tokenManager.getToken();

  // 3. Fazer requisição à Banking API
  const response = await fetch(
    `https://api.bancodigital.com/public/gw_banking/v1/accounts/${req.params.id}/balance`,
    {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    },
  );

  // 4. Retornar resposta ao frontend
  const data = await response.json();
  res.json(data);
});

✅ Rate Limiting

// Exemplo: Rate limiting por usuário
import rateLimit from 'express-rate-limit';

const bankingApiLimiter = rateLimit({
  windowMs: 1 * 60 * 1000, // 1 minuto
  max: 100, // 100 requisições por minuto por usuário
  keyGenerator: (req) => {
    // Usar ID do usuário como chave
    return req.user.id;
  },
});

app.use('/api/banking', bankingApiLimiter);

✅ Logging e Auditoria

// Exemplo: Logging de todas as requisições
app.use('/api/banking', (req, res, next) => {
  logger.info({
    userId: req.user.id,
    endpoint: req.path,
    method: req.method,
    timestamp: new Date().toISOString(),
    x,
  });
  next();
});

Tecnologias Recomendadas

Node.js: Express, Fastify, NestJS
Python: FastAPI, Flask
Java: Spring Boot
Go: Gin, Echo

Importante: O BFF deve rodar em servidor seguro, nunca no navegador do usuário.

2️⃣ Sistema de Autenticação

O que é necessário?

Você precisa ter um sistema de autenticação que:

Valida credenciais de usuários finais (login/senha, 2FA, etc)
Gerencia sessões de forma segura
Emite tokens de sessão que seu BFF pode validar
Implementa políticas de segurança (senha forte, bloqueio de conta, etc)

Funcionalidades Mínimas

✅ Autenticação de Usuários

// Exemplo: Login de usuário
async function loginUser(email: string, password: string) {
  // 1. Validar credenciais
  const user = await userService.validateCredentials(email, password);

  // 2. Verificar 2FA se necessário
  if (user.requires2FA) {
    await twoFactorService.sendCode(user.id);
    return { requires2FA: true };
  }

  // 3. Criar sessão
  const sessionToken = await sessionService.createSession(user.id);

  return {
    sessionToken,
    user: {
      id: user.id,
      email: user.email,
    },
  };
}

✅ Validação de Sessão

// Exemplo: Middleware de validação de sessão
async function validateSession(req, res, next) {
  const sessionToken = req.headers.authorization?.replace('Bearer ', '');

  if (!sessionToken) {
    return res.status(401).json({ error: 'Token não fornecido' });
  }

  const session = await sessionService.validateSession(sessionToken);

  if (!session || session.expiresAt < new Date()) {
    return res.status(401).json({ error: 'Sessão inválida ou expirada' });
  }

  req.user = await userService.getUserById(session.userId);
  next();
}

✅ Logout e Revogação

// Exemplo: Logout
async function logoutUser(sessionToken: string) {
  await sessionService.revokeSession(sessionToken);
}