🛡️ Estrutura de Autenticação Segura

Serviços Separados para Web e API

Documento Técnico - Arquitetura MVC PHP 8.2+

📘 Visão Geral

Este documento tem como objetivo padronizar, documentar e orientar a implementação dos serviços de autenticação utilizados no projeto, respeitando o padrão arquitetural MVC, com divisão clara entre autenticação para interface Web (baseada em sessões) e autenticação para API (baseada em JWT).

Optamos por separar os serviços de autenticação para garantir clareza, modularidade e facilidade de manutenção, evitando mistura de responsabilidades.

🗂️ Estrutura de Arquivos

App/
├── src/
│   ├── Controller/
│   │   ├── AuthController.php         # Requisições de login Web
│   │   └── AuthApiController.php      # Requisições da API (JSON)
│   ├── Service/
│   │   ├── AuthService.php            # Autenticação Web (sessões)
│   │   └── AuthApiService.php         # Autenticação API (JWT)
│   └── Model/
│       └── User.php                   # Representa o usuário, contém getByEmail()

📦 Descrição dos Componentes

🔹 AuthService.php (Autenticação Web)

namespace App\Service;

class AuthService
{
    public function login(string $email, string $password): bool;
    public function logout(): void;
    public function isAuthenticated(): bool;
    private function verifyPassword(string $hash, string $plain): bool;
}

Função: Realiza login tradicional com sessões, ideal para navegadores.

• Armazena o ID do usuário autenticado via $_SESSION.
• Sanitiza entrada antes de consultar o banco.
• Encapsula verificação com password_verify().

🔹 AuthApiService.php (Autenticação API)

namespace App\Service;

use Firebase\JWT\JWT;
use Firebase\JWT\Key;

class AuthApiService
{
    public function login(string $email, string $password): ?string;
    public function verifyToken(string $token): ?array;
    private function generateToken(array $payload): string;
    private function verifyPassword(string $hash, string $plain): bool;
}

Função: Autentica via JWT, retornando token para requisições protegidas da API.

• Geração segura de token com HS256.
• Payload inclui expiração (exp).
• Modularização permite troca de algoritmo.

🔄 Diferença de Fluxos

✅ Boas Práticas de Nomenclatura

• Prefixos como login, logout, verifyToken tornam o serviço autoexplicativo.
• Evite misturar autenticação com persistência — use User.php ou um UserRepository.
• Mantenha métodos privados como verifyPassword() e generateToken() encapsulados.

🔐 Segurança Adicional

• Use password_hash() com bcrypt ou argon2id.
• Tokens JWT devem conter: iat, exp, iss, sub.
• Armazene o segredo JWT em variáveis de ambiente no ambiente de produção.
• Proteja rotas de API com middleware para validar o token e extrair o ID do usuário.

🧪 Exemplo de uso em AuthApiController.php

namespace App\Controller;

use App\Service\AuthApiService;

class AuthApiController
{
    public function login(): void
    {
        $data = json_decode(file_get_contents('php://input'), true);

        $authService = new AuthApiService();
        $token = $authService->login($data['email'], $data['password']);

        if (!$token) {
            http_response_code(401);
            echo json_encode(['error' => 'Credenciais inválidas']);
            return;
        }

        echo json_encode(['token' => $token]);
    }
}

🧭 Caminhos para evolução futura

• Adicionar refresh token com tempo maior.
• Implementar bloqueio após X tentativas falhas.
• Registrar logins com IP, hora e user-agent.
• Unificar serviços com uma AuthInterface.

📚 Referências e Fontes

• PHP Manual – Sessions
• Firebase PHP-JWT
• OWASP Authentication Cheat Sheet
• PSR-4: Autoloading Standard
• PSR-12: Coding Style