Especificação de Requisitos: Segurança no Acesso e Geração de Chaves de API (req-033)

Esta especificação define o lote de trabalho req-033 (BATCH-033) para o Engenheiro Executor. O escopo abrange o endurecimento de segurança da rota de geração de tokens de API (oauth-authenticate/), incluindo o controle dos métodos de autenticação permitidos, imposição de 2FA interativo para emissão de chaves, e controle dinâmico dos perfis de usuários autorizados a gerar tokens através de uma nova aba no painel administrativo.

1. Configurações Globais no Módulo admin-environment

Criar uma nova aba chamada API (data-tab="api") na interface do admin-environment (admin-environment.html em pt-br e en). Esta aba conterá os seguintes controles:

1.1 Controle de Perfis Permitidos

• Configuração: AUTH_API_ALLOWED_PROFILES (Salvo no .env como uma lista de IDs de perfis separados por vírgula).

• Interface: Exibir uma lista de checkboxes com todos os perfis de usuários disponíveis (obtidos da tabela usuarios_perfis com status != 'D').

• Objetivo: O administrador poderá marcar quais perfis de usuários possuem permissão para acessar a rota e gerar chaves de API.

1.2 Toggles de Métodos de Autenticação para API

• Variáveis:

  • AUTH_API_METHOD_PASSWORD_ACTIVE (Checkbox, default true): Habilita autenticação por senha para gerar tokens de API.

  • AUTH_API_METHOD_EMAIL_ACTIVE (Checkbox, default false): Habilita autenticação sem senha (código por e-mail) para gerar tokens de API.

1.3 Imposição e Configurações de 2FA para API

• Variável: AUTH_API_2FA_REQUIRED (Checkbox, default false): Se ativo, obriga a validação do segundo fator (2FA) para concluir a emissão do token da API.

• Métodos 2FA Permitidos para API:

  • AUTH_API_2FA_METHOD_APP (Checkbox, default true): Permite usar Aplicativo Autenticador (TOTP).

  • AUTH_API_2FA_METHOD_EMAIL (Checkbox, default true): Permite usar código enviado por E-mail.

2. Fluxo de Geração de Token com 2FA (oauth-authenticate/)

O controlador backend da rota de autenticação da API (perfil_usuario_oauth_authenticate() em perfil-usuario.php) e seus templates de interface devem ser estendidos para implementar os novos requisitos de segurança.

2.1 Validação de Perfil Autorizado

• Ao carregar a rota oauth-authenticate/ (tanto GET quanto POST), ler a lista de perfis permitidos em AUTH_API_ALLOWED_PROFILES.

• Comparar o perfil do usuário tentando se autenticar (id_usuarios_perfis). Se o ID do perfil não estiver listado, bloquear o acesso imediatamente retornando erro de falta de permissão.

2.2 Autenticação Inicial

• O formulário de login da API em oauth-authenticate deve adaptar sua interface de forma idêntica ao login do sistema:

  • Ocultar campo de senha se apenas o login por código de e-mail estiver ativo.

  • Exibir abas/alternadores Fomantic UI se ambos os métodos (senha e e-mail) estiverem ativos.

• Se o usuário autenticar com sucesso (seja via senha válida ou via código enviado por e-mail e validado):

  • Verificar se a segurança 2FA deve ser aplicada:

  • Se AUTH_API_2FA_REQUIRED for true globalmente, OU se o usuário possuir two_factor_enabled = 1 ativo em sua conta.

2.3 Interceptador 2FA e Holding de Tokens

• Se o 2FA se aplicar:

  • O backend não emite o token imediatamente.

  • Gera os dados de resposta dos tokens e os mantém temporariamente nas variáveis de sessão do gestor (gestor_sessao_variavel):

  • pending_oauth_tokens = array contendo os tokens gerados.

  • pending_oauth_user = ID do usuário.

  • pending_oauth_mode = 'verify'.

  • pending_oauth_type = tipo de 2FA cadastrado do usuário (ou o método padrão permitido se for imposição global e ele não tiver configurado).

  • Se o tipo de 2FA for E-mail, dispara o código OTP de 6 dígitos via two_factor_email_send_code().

  • Redireciona o usuário para a nova tela de verificação: oauth-authenticate-2fa/.

2.4 Tela de Verificação oauth-authenticate-2fa/ [NEW]

• Criar a rota/página correspondente oauth-authenticate-2fa/ no módulo de perfil de usuário.

• A tela exibe o input de 6 dígitos para o código de segurança (com a opção de reenviar por e-mail se o tipo for e-mail).

• Ao submeter o formulário (POST):

  • Validar o código contra o segredo TOTP do usuário (se tipo app) ou contra o código temporário no banco (se tipo email).

  • Se o código for válido:

  • Recuperar a resposta de tokens armazenada em pending_oauth_tokens.

  • Limpar as variáveis de sessão temporárias (pending_oauth_*).

  • Concluir o fluxo original retornando a resposta (redirecionar com parâmetros ou imprimir JSON de tokens).

  • Se for inválido, exibir mensagem de erro e travar o fluxo.

3. Critérios de Aceitação e Validação

• Validação de Filtro de Perfil: Tentar gerar chave com um usuário cujo perfil de acesso não esteja marcado na aba API e garantir o bloqueio.

• Validação de 2FA: Com a imposição ativa, simular a requisição de token e comprovar o redirecionamento para oauth-authenticate-2fa/, garantindo que o token só é exposto após digitação do código OTP correto.

• Validação de Métodos: Confirmar a alternância dos campos na tela de autenticação da API de acordo com os toggles ativos (senha vs e-mail).

• Validação de Linting: Executar php -l em todos os arquivos modificados.