Escopos de Origem

Os Escopos de Origem definem as políticas de acesso e autorização que determinam quem e como um fluxo de integração pode ser acionado na Engine. Trata-se de uma camada de governança e segurança aplicada no momento da publicação da versão, garantindo que fluxos sensíveis de infraestrutura não fiquem expostos involuntariamente à internet.

---

Os Três Escopos de Execução

Cada versão publicada em um ambiente possui um mapa de escopos permitidos (PUBLICO, INTERNO e AGENDADOR). Durante o recebimento de uma requisição, a Engine valida se a rota acessada é compatível com os escopos liberados para aquela publicação.

Escopos de execução

                     ┌─────────────────────────────────┐
                     │        REQUISIÇÃO HTTP          │
                     └────────────────┬────────────────┘
                                      │
            ┌─────────────────────────┼─────────────────────────┐
            ▼                         ▼                         ▼
┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
│    Escopo PUBLICO     │ │    Escopo INTERNO     │ │   Escopo AGENDADOR    │
│  /v1/core/public/...  │ │ /v1/core/internal/... │ │/v1/core/scheduler/... │
└───────────┬───────────┘ └───────────┬───────────┘ └───────────┬───────────┘
            │                         │                         │
            ▼                         ▼                         ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                      VALIDAÇÃO DE ESCOPO NA ENGINE                        │
│   (Rejeita com HTTP 404/403 se o escopo acessado não estiver liberado)    │
└───────────────────────────────────────────────────────────────────────────┘

Escopo Público (`PUBLICO`)

Destinado a integrar o ecossistema com o mundo externo, como aplicações web, aplicativos móveis, webhooks de terceiros ou sistemas corporativos parceiros.

Escopo Interno (`INTERNO`)

Destinado exclusivamente à comunicação privada e comunicação entre processos dentro do próprio ecossistema.

Escopo Agendador (`AGENDADOR`)

Destinado ao acionamento automático disparado pelo componente de agendamento temporal de tarefas.

---

1. Escopo Público (PUBLICO)

• Rotas Disponíveis:

• Síncrona: POST /v1/core/public/{slugProjeto}/{slugPacote}/{slugFluxo}

• Assíncrona: POST /v1/core/async/public/{slugProjeto}/{slugPacote}/{slugFluxo}

• Identificação de Rota: A resolução ocorre obrigatoriamente por Slugs.

• Mecanismos de Defesa: É o único escopo que aplica validações rígidas de CORS (web_origin) e exige a validação de Chaves de API (API Keys com hash SHA-256) antes de autorizar o início da sessão.

• Timeout Síncrono Padrão: Possui um tempo limite curto de espera (padrão de 5 segundos) para garantir respostas rápidas a clientes web.

2. Escopo Interno (INTERNO)

• Rotas Disponíveis:

• Síncrona: POST /v1/core/internal/{coFluxo}

• Assíncrona: POST /v1/core/async/internal/{coFluxo}

• Identificação de Rota: A resolução ocorre diretamente pelo Código do Fluxo (coFluxo).

• Casos de Uso Principais:

• Invocação de subfluxos desacoplados através do runner de Autorreferência.

• Chamadas vindas de microsserviços confiáveis rodando na mesma rede privada ou malha de serviços.

• Isolamento de Segurança: O bloqueio deste escopo impede que subfluxos projetados para processamento interno sejam acessados diretamente pela internet através das rotas públicas.

• Timeout Síncrono Padrão: Suporta tempos de espera mais longos (padrão de 30 segundos) para acomodar o processamento de rotinas complexas.

3. Escopo Agendador (AGENDADOR)

• Rotas Disponíveis:

• Síncrona: POST /v1/core/scheduler/{coFluxo}

• Assíncrona: POST /v1/core/async/scheduler/{coFluxo}

• Identificação de Rota: A resolução ocorre pelo Código do Fluxo (coFluxo).

• Funcionamento: O Agendador consulta os agendamentos vigentes, constrói o payload pré-configurado e invoca a Engine no ambiente de destino.

• Controle de Acesso: Permite isolar fluxos que devem rodar exclusivamente de forma automática (ex: rotinas de varredura noturna, sincronização de bases e consolidação de relatórios), impedindo invocações manuais via rotas públicas.

• Timeout Síncrono Padrão: Suporta tempo estendido de espera (padrão de 30 segundos).

---

Pipeline de Validação na Engine

Quando a requisição chega à Engine, a verificação do escopo de origem é a terceira etapa do pipeline sequencial de validação de sessão:

1. Resolução de Fluxo

   Identifica o fluxo e a versão ativa.

2. Validação do Inicializador HTTP

   Checa se o método HTTP é aceito pelo fluxo.

3. Validação do Escopo de Origem

   A Engine verifica se o escopo da rota acessada (PUBLICO, INTERNO ou AGENDADOR) está presente na lista de escopos liberados no cadastro de publicação da versão. Se a origem não for permitida, a requisição é interrompida com um erro de Escopo Não Permitido (HTTP 404 Not Found ou 403 Forbidden).

4. Validação de Segurança

   Aplica verificações de CORS e API Key (se aplicável ao escopo público).

5. Extração de Parâmetros e Criação de Sessão

   Processa os dados de entrada e despacha o contexto para execução pelos runners.