📖 Documentação da API Vanguru (Firebase Functions)

Este documento detalha as funções disponíveis no backend para garantir a conformidade com a LGPD e a segurança financeira do projeto Vanguru. Todas as funções são do tipo HTTPS Callable.

🔐 Camada de Segurança e LGPD

1. secureUpsertSensitiveData

Criptografa dados sensíveis antes de salvá-los no Firestore. O dado original nunca toca o banco de dados em texto claro.

Parâmetros de Entrada:

{
  "collection": "string", // "users", "passengers" ou "responsibles"
  "docId": "string",      // ID do documento correspondente na coleção principal
  "data": {               // Objeto com os campos sensíveis
    "cpf": "12345678900",
    "birthDate": "2010-01-01"
  }
}

Retorno:

{
  "success": true,
  "timestamp": "ISO-8601-String"
}

Comportamento: - Os campos são salvos com o sufixo _enc na respectiva coleção de cofre (ex: responsibles_sensitive). - Utiliza AES-256 com a MASTER_KEY configurada no ambiente.

2. secureReadSensitiveData

Recupera e descriptografa dados sob demanda. Ideal para casos de "revelar informação" ou processos de backend que não podem ser feitos no cliente.

Parâmetros de Entrada:

{
  "collection": "string", // "users", "passengers" ou "responsibles"
  "docId": "string",
  "fields": ["string"]    // Lista de campos a serem descriptografados
}

Retorno:

{
  "cpf": "12345678900",
  "birthDate": "2010-01-01"
}

Comportamento: - Cada chamada gera um log de auditoria no Cloud Logging: [AUDIT] User {UID} accessed fields [...]. - Se o documento ou campo não existir, retorna um objeto vazio ou apenas os campos encontrados.

3. secureBatchUpsertSensitiveData

Permite o envio de múltiplos dados sensíveis em uma única operação (Batch). É ideal para situações onde múltiplos documentos precisam ser atualizados simultaneamente (ex: importação ou sincronização de dados), reduzindo o número de requisições HTTPS.

Parâmetros de Entrada:

{
  "operations": [
    {
      "collection": "string", // "users", "passengers", "responsibles", ou "users/*/sensitive"
      "docId": "string",
      "data": {
        "cpf": "11122233300"
      }
    },
    {
      "collection": "passengers",
      "docId": "child_abc",
      "data": {
        "rg": "12345678"
      }
    }
  ]
}

Retorno:

{
  "success": true,
  "count": 2
}

Comportamento: - Utiliza o writeBatch do Firestore para garantir atomicidade no nível do banco de dados (dentro dos limites do Firestore). - Suporta os mesmos mapeamentos de coleção da função individual.

💳 Integração Financeira

4. createAsaasSubscription

Intermediário seguro para a API do Asaas. Garante que a chave de API do Asaas nunca saia do ambiente do servidor.

Parâmetros de Entrada (Exemplo):

{
  "customer": "customer_id",
  "billingType": "BOLETO",
  "value": 150.00,
  "nextDueDate": "2026-02-05"
}

Retorno:

{
  "asaasSubscriptionId": "string",
  "status": "string",
  "timestamp": "string"
}

Comportamento: - Injeta automaticamente a ASAAS_API_KEY nos cabeçalhos da requisição para o Asaas.

🛠️ Configuração de Ambiente (Secrets)

Para que as funções operem corretamente em produção, execute os seguintes comandos no terminal:

# Configurar chave mestra de criptografia
firebase functions:secrets:set MASTER_KEY

# Configurar chave de API do Asaas
firebase functions:secrets:set ASAAS_API_KEY

📱 Exemplo de Integração Flutter (Dart)

import 'package:cloud_functions/cloud_functions.dart';

Future<Map<String, dynamic>> getCpf(String responsibleId) async {
  try {
    final result = await FirebaseFunctions.instance
        .httpsCallable('secureReadSensitiveData')
        .call({
      "collection": "responsibles",
      "docId": responsibleId,
      "fields": ["cpf"],
    });
    return Map<String, dynamic>.from(result.data);
  } catch (e) {
    print("Erro ao ler CPF: $e");
    rethrow;
  }
}

// Exemplo de Upsert em Lote (Batch)
Future<void> saveMultipleSensitive(List<Map<String, dynamic>> ops) async {
  try {
    await FirebaseFunctions.instance
        .httpsCallable('secureBatchUpsertSensitiveData')
        .call({
      "operations": ops,
    });
  } catch (e) {
    print("Erro no batch: $e");
    rethrow;
  }
}

💻 Ambiente de Desenvolvimento Local

Para executar e testar o projeto localmente, siga os passos abaixo.

Pré-requisitos

  • Node.js: Versão 20 (LTS)
  • Firebase CLI: npm install -g firebase-tools
  • Java: Necessário para emuladores (Firestore/Auth)

Configuração Inicial

  1. Instale as dependências: bash npm install
  2. Configure as variáveis de ambiente: bash cp .env.template .env # Edite o arquivo .env com suas chaves locais (pode usar valores fictícios para desenvolvimento local se não interagir com APIs reais)

Executando Emuladores

O projeto está configurado para emular Functions, Firestore e Auth.

npm run serve
# ou
firebase emulators:start

O VFS (Emulator UI) estará disponível em http://localhost:4000.

Executando Testes

Testes unitários utilizam mocha e chai.

npm test

🚀 CI/CD (GitHub Actions)

O projeto possui pipelines automatizados para garantir a qualidade e o deploy contínuo.

Workflows

  1. Run Tests (run-tests.yml):
  2. Gatilho: Pull Request p/ main, develop e Push p/ develop.

  3. Ação: Instala dependências, roda lint (npm run lint) e executa testes unitários (npm test).

  4. Deploy Functions (deploy-functions.yml):

  5. Gatilho: Push direto na branch main.
  6. Ação: Faz o deploy automático das funções para o Firebase.
  7. Secret Necessária: FIREBASE_SERVICE_ACCOUNT_KEY deve estar configurada nos Secrets do repositório GitHub.

🆚 VS Code Setup

O projeto inclui configurações para facilitar o desenvolvimento no VS Code.

  • Tasks: Use Cmd+Shift+P -> Tasks: Run Task -> Start Firebase Emulators para iniciar o ambiente local.
  • Debug: Fica pronto para anexar debugger se configurado (porta 9229 padrão do node inspector quando rodando em modo debug).