Camada Kernel

O núcleo do sistema. Entenda cada componente de src/Kernel/.

Regra de ouro

Você raramente precisará modificar o Kernel. Ele foi projetado para ser estável e extensível via módulos.

Nucleo/ — O coração

Container.php

Container de Injeção de Dependência. Resolve classes automaticamente via Reflection. Suporta singletons, bindings e resolução recursiva.

Router.php

Roteador HTTP. Suporta GET, POST, PUT, PATCH, DELETE. Parâmetros dinâmicos ({uuid}), middlewares por rota e pipeline em cadeia.

Application.php

Orquestra o boot: carrega módulos, registra rotas, executa BotBlocker e SecurityHeaders globalmente, despacha a requisição.

ModuleLoader.php

Descobre e carrega módulos automaticamente de src/Modules/. Chama boot() e registerRoutes() de cada provider.

PluginManager.php

Gerencia plugins externos (instalação, ativação, desativação, remoção). Persiste estado em storage/.

CapabilityResolver.php

Sistema de capacidades. Permite que módulos declarem e consumam serviços (ex: email-sender) sem acoplamento direto.

Middlewares/

Todos os middlewares implementam MiddlewareInterface e seguem o padrão onion (cebola).

Middleware	Função
`AuthHybridMiddleware`	Autentica via JWT (cookie ou header Authorization). Valida assinatura, claims, blacklist e UUID.
`AdminOnlyMiddleware`	Restringe acesso a `admin_system` com token assinado por `JWT_API_SECRET`.
`AuthCookieMiddleware`	Autentica exclusivamente via cookie `auth_token`. Valida JWT e blacklist.
`AuthPageMiddleware`	Autenticação para páginas HTML do dashboard. Redireciona para `/` se não autenticado.
`OptionalAuthHybridMiddleware`	Autentica se token presente, mas não obriga. Útil para rotas públicas com dados extras para autenticados.
`ApiTokenMiddleware`	Autenticação via token de API (tipo `api` no JWT, assinado com `JWT_API_SECRET`).
`RateLimitMiddleware`	Rate limiting por IP + usuário. Redis (distribuído) ou File (servidor único). Configurável por rota.
`BotBlockerMiddleware`	Bloqueia User-Agents de scanners (sqlmap, nikto, nmap...). Aplica delay progressivo por ThreatScore.
`SecurityHeadersMiddleware`	Injeta CSP, HSTS, X-Frame-Options, CORP, COEP, COOP em todas as respostas globalmente.
`CircuitBreakerMiddleware`	Protege contra falhas em cascata. Estados: CLOSED → OPEN → HALF. Persiste em Redis ou File.
`RouteProtectionMiddleware`	Proteção genérica de rotas com validação de JWT e roles. Aceita token de usuário ou de API.
`HttpsEnforcerMiddleware`	Redireciona HTTP → HTTPS quando `COOKIE_SECURE=true`.

Como usar um middleware em uma rota

php

// Rota pública — sem middleware
$router->get('/api/status', [StatusController::class, 'index']);

// Rota autenticada
$router->get('/api/perfil', [PerfilController::class, 'index'], [
    AuthHybridMiddleware::class,
]);

// Rota admin com rate limit
$router->post('/api/usuarios', [UsuarioController::class, 'criar'], [
    AuthHybridMiddleware::class,
    AdminOnlyMiddleware::class,
    [RateLimitMiddleware::class, ['limit' => 5, 'window' => 60, 'key' => 'usuario.criar']],
]);

Support/ — Utilitários

Arquivo	Função
`JwtDecoder.php`	Decodifica e valida tokens JWT. Suporta key rotation via `kid`, validação de `iss` e `aud`.
`ThreatScorer.php`	Acumula pontos de comportamento suspeito por IP. Threshold 150 = bloqueio. TTL 1h.
`AuditLogger.php`	Registra eventos de segurança no banco e stderr (Fail2Ban). Detecta brute force automaticamente.
`SecurityEventLogger.php`	Logger estruturado JSON para THREAT, AUTH, BUSINESS_LOGIC, ABUSE. Integra com Datadog/CloudWatch.
`IdempotencyLock.php`	Distributed lock via Redis SET NX ou flock. Previne race conditions em operações críticas.
`IpResolver.php`	Resolve IP real do cliente respeitando `TRUST_PROXY` e `X-Forwarded-For`.
`OwnershipGuard.php`	Verifica se o usuário autenticado é dono do recurso. Previne IDOR.
`MailerService.php`	Envio de e-mails via SMTP (PHPMailer). Suporta HTML, templates e throttling.
`EmailHistory.php`	Persiste historico de e-mails enviados. Busca, filtra e deleta registros.
`EmailThrottle.php`	Controla throttle de envio por tipo e e-mail. Cooldown configuravel (padrao 120s).
`CookieConfig.php`	Centraliza configuracao de cookies. Detecta HTTPS via porta, header e TRUST_PROXY.
`TokenExtractor.php`	Extrai token JWT do header Authorization: Bearer ou X-API-KEY.
`RequestContext.php`	Contexto da requisicao: request_id, IP, user_agent. Injetado em Logger e AuditLogger.
`Logger.php`	Logger estruturado JSON em stderr. Suprime logs em testing. Compativel com Docker/K8s.
`Storage/`	RateLimitStorageFactory, RedisRateLimitStorage, FileRateLimitStorage.
`DB/`	Migrator, PluginMigrator - execucao de migrations do core e plugins.

Utils/ - Utilitarios de dominio

Arquivo	Funcao
`Sanitizer.php`	Sanitizacao de inputs: string, email, username, positiveInt, nivelAcesso, uuid, search, url, text, password.
`ImageProcessor.php`	Redimensiona e salva imagens (JPEG, PNG, WebP). Preserva transparencia. Fallback se GD indisponivel.
`RelogioTimeZone.php`	Singleton para timezone. Le APP_TIMEZONE do .env. Retorna DateTimeImmutable com timezone correto.

Http/ — Request e Response

php

// Response JSON
return Response::json(['status' => 'ok', 'data' => $dados]);
return Response::json(['error' => 'Não encontrado'], 404);

// Response HTML
return Response::html($html);

// Acessar dados da requisição
$body    = $request->body;          // array do JSON body
$query   = $request->query;         // query string params
$usuario = $request->attribute('auth_user'); // injetado pelo AuthMiddleware
$uuid    = $request->param('uuid');  // parâmetro de rota {uuid}

Contracts/ — Interfaces

As interfaces definem contratos que o Kernel usa internamente. Módulos podem implementá-las para integrar com o sistema:

Interface	Implementação padrão
`UserRepositoryInterface`	`Modules/Usuario/Repositories/UsuarioRepository`
`TokenBlacklistInterface`	`Modules/Auth/Repositories/AccessTokenBlacklistRepository`
`EmailSenderInterface`	`Kernel/Support/MailerService`
`RateLimitStorageInterface`	`RedisRateLimitStorage` ou `FileRateLimitStorage`
`ModuleProviderInterface`	Implementada por cada módulo em seu ServiceProvider
`RouterInterface`	`Kernel/Nucleo/Router`
`ContainerInterface`	`Kernel/Nucleo/Container`
`MiddlewareInterface`	Todos os middlewares em `Kernel/Middlewares/`
`TenantResolverInterface`	Resolução de tenant (subdomínio, path, header, JWT)