README

O Cerbero SDK é uma biblioteca PHP robusta e leve projetada para centralizar e simplificar as operações de autenticação, verificação de sessão, controle de acesso a múltiplos sistemas e autorização granular de permissões (diretas e baseadas em perfis de usuário / RBAC).

Sumário

Recursos
Requisitos
Instalação
Estrutura do Banco de Dados
Configuração
Guia de Uso
Tratamento de Exceções
Enumerações de Status
Exemplo Prático (Web Demo)
Testes e Qualidade de Código
Licença

Recursos

🔐 Autenticação Segura: Suporte nativo à validação de hash de senhas (password_verify), compatível com Argon2id, Bcrypt, etc.
🛡️ Proteção contra Brute Force: Controle opcional de tentativas consecutivas de login (maxLoginAttempts).
🎟️ Gestão de Sessão: Geração e validação de tokens únicos de sessão por usuário.
🏢 Multi-Sistemas: Controle de acesso isolado por slug de sistema.
🔑 Autorização Flexível (RBAC):
- Permissões atribuídas diretamente ao usuário no sistema.
- Permissões herdadas através de perfis (roles) atribuídos ao usuário.
🧱 Enums Tipados: Status padronizados para usuários, sistemas, permissões, perfis e relacionamentos.
🧪 Alta Qualidade: 100% de cobertura de tipos e análise estática avançada com PHPStan.

Requisitos

PHP: >= 8.5.7
Extensão PDO ativa com o driver do banco de dados desejado (SQLite, MySQL, PostgreSQL, etc.).

Instalação

Adicione o Cerbero SDK ao seu projeto via Composer:

composer require cerbero/cerbero-sdk

Estrutura do Banco de Dados

O Cerbero SDK utiliza uma estrutura relacional simples e eficiente com o prefixo crb_:

Tabela	Descrição
`crb_users`	Registra os usuários, hash de senha, token de sessão atual, status e tentativas de login.
`crb_systems`	Sistemas cadastrados identificados por `slug` e `status`.
`crb_permissions`	Permissões disponíveis por sistema (`system_slug`, `slug`).
`crb_profiles`	Perfis/papéis disponíveis por sistema (`system_slug`, `slug`).
`crb_user_system`	Vínculo de acesso de usuários a sistemas.
`crb_user_permission`	Permissões concedidas diretamente a usuários específicos.
`crb_user_profile`	Perfis atribuídos a cada usuário por sistema.
`crb_profile_permission`	Permissões vinculadas a perfis específicos por sistema.

Os scripts SQL de criação do esquema e dados de exemplo estão localizados no diretório migrations/.

Configuração

O SDK é instanciado recebendo um array associativo de configurações:

use Cerbero\Sdk\Cerbero;

$config = [
    'pdoDsn' => 'sqlite:/caminho/para/o/banco.db', // DSN de conexão PDO
    'pdoUser' => null,                             // Usuário do banco (opcional)
    'pdoPass' => null,                             // Senha do banco (opcional)
    'pdoOptions' => [                              // Opções do driver PDO (opcional)
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    ],
    'maxLoginAttempts' => 3                        // Limite de tentativas de login antes do bloqueio (opcional)
];

$crb = new Cerbero($config);

Guia de Uso

1. Inicializando o SDK

require_once __DIR__ . '/vendor/autoload.php';

use Cerbero\Sdk\Cerbero;

$crb = new Cerbero([
    'pdoDsn' => 'sqlite:./cerbero.db',
    'maxLoginAttempts' => 3
]);

2. Autenticação de Usuários (`authenticate`)

Valida o identificador do usuário e a senha em texto plano. Se corretos, gera um novo token de sessão, reseta as tentativas de login e retorna o token gerado.

use Cerbero\Sdk\Exception\UserOrPasswordInvalid;
use Cerbero\Sdk\Exception\LimitLoginAttempts;

try {
    $sessionToken = $crb->authenticate('admin', 'minha_senha_123');
    
    // Armazena na sessão da aplicação web
    $_SESSION['user_id'] = 'admin';
    $_SESSION['session_token'] = $sessionToken;
} catch (UserOrPasswordInvalid $e) {
    echo "Usuário ou senha incorretos.";
} catch (LimitLoginAttempts $e) {
    echo "Limite de tentativas de login excedido. Tente novamente mais tarde.";
}

3. Verificação de Autenticação (`authenticated` e `checkSessionToken`)

authenticated(string $userId, string $sessionToken): bool: Valida se o usuário existe, está ativo e possui o token de sessão correspondente.
checkSessionToken(?string $sessionToken): bool: Consulta se determinado token de sessão existe atribuído a algum usuário.

$userId = $_SESSION['user_id'] ?? '';
$sessionToken = $_SESSION['session_token'] ?? '';

if ($crb->authenticated($userId, $sessionToken)) {
    echo "Sessão válida para o usuário $userId.";
} else {
    echo "Usuário não autenticado ou sessão expirada.";
}

4. Controle de Acesso a Sistemas (`access`)

Verifica se o usuário possui vínculo ativo com o sistema solicitado (systemSlug).

use Cerbero\Sdk\Exception\UserNotAuthenticated;

try {
    if ($crb->access($userId, $sessionToken, 'financeiro')) {
        echo "Acesso permitido ao módulo Financeiro.";
    } else {
        echo "Acesso negado ao módulo Financeiro.";
    }
} catch (UserNotAuthenticated $e) {
    // Redirecionar para tela de login
}

5. Autorização de Permissões (`authorizated`)

Verifica se o usuário possui determinada permissão (permissionSlug) em um sistema (systemSlug). A validação avalia:

Permissões concedidas diretamente ao usuário (crb_user_permission).
Permissões concedidas por meio dos perfis do usuário (crb_user_profile + crb_profile_permission).

use Cerbero\Sdk\Exception\UserNotAuthorized;

try {
    // Verifica permissão de exclusão no sistema financeiro
    if ($crb->authorizated($userId, $sessionToken, 'financeiro', 'delete')) {
        echo "Usuário autorizado a excluir registros.";
    } else {
        echo "Permissão negada.";
    }
} catch (UserNotAuthorized $e) {
    echo "Usuário não possui acesso ao sistema solicitado.";
}

6. Encerramento de Sessão / Logoff (`unauthenticate`)

Invalida o token de sessão do usuário no banco de dados.

$crb->unauthenticate($userId);

// Limpa a sessão local da aplicação
session_destroy();

Tratamento de Exceções

O SDK dispara exceções específicas derivadas de \RuntimeException:

Exceção	Quando ocorre
`UserNotAuthenticated`	Disparada ao tentar verificar acesso a sistemas sem uma sessão ativa e autenticada.
`UserNotAuthorized`	Disparada ao tentar verificar permissões sem possuir acesso prévio ao sistema.
`UserOrPasswordInvalid`	Disparada quando o ID de usuário não existe ou a senha informada é incorreta.
`LimitLoginAttempts`	Disparada quando a quantidade de falhas consecutivas de login atinge o limite configurado em `maxLoginAttempts`.

Enumerações de Status

Todas as entidades e relacionamentos utilizam enums inteiros (int) tipados:

UserStatus: Undefined (0), Active (1), Pending (2), Disabled (3)
SystemStatus: Undefined (0), Active (1), Disabled (3)
PermissionStatus: Undefined (0), Active (1), Disabled (3)
ProfileStatus: Undefined (0), Active (1), Disabled (3)
RelationStatus: Undefined (0), Active (1), Disabled (3)

Exemplo Prático (Web Demo)

O diretório examples/ contém uma aplicação web demonstrativa completa utilizando Fomantic-UI.

Para rodar o exemplo localmente com o servidor embutido do PHP:

php -S localhost:8000 -t examples/

Em seguida, acesse no navegador: http://localhost:8000

Credenciais de teste padrão (senha: abc123):

Usuário admin: Acesso total e permissões completas.
Usuário editor: Permissões via perfil (create, read, update).
Usuário guest: Apenas leitura (read).

Testes e Qualidade de Código

O projeto conta com ferramentas automatizadas configuradas no composer.json para garantir qualidade, segurança de tipos e conformidade com padrões de código:

# Executar a suíte de testes com cobertura HTML e validação de tipos (Pest)
composer test

# Executar a análise estática avançada (PHPStan Nível 6)
composer static

# Executar correção e validação de padrões de código PSR (PSR-1, PSR-2 e PSR-12)
composer code

# Corrigir automaticamente inconformidades de estilo no diretório sdk/ (phpcbf)
composer fix-code

# Inspecionar conformidade com padrões PSR no diretório sdk/ (phpcs)
composer psr-code

Detalhamento dos Scripts

composer test: Executa a suíte de testes do Pest, gerando o relatório de cobertura de código em coverage/html/ e avaliando a cobertura de tipos estáticos (100%).
composer static: Executa o PHPStan (vendor/bin/phpstan analyse) para detecção estática de erros e consistência de tipos.
composer code: Encadeia a correção automática (@fix-code) e a validação (@psr-code) de conformidade com os padrões PSR-1, PSR-2 e PSR-12.
composer fix-code: Utiliza o phpcbf para formatar e corrigir automaticamente o código do diretório sdk/.
composer psr-code: Utiliza o phpcs para validar a conformidade do código do diretório sdk/ com as especificações PSR.

Licença

Este projeto é distribuído sob a licença MIT. Consulte o arquivo composer.json para mais informações.

Autor: Everton da Rosa (everton3x@gmail.com)

everton3x / cerbero-sdk

Package info

Security

Statistics

README

Sumário

Recursos

Requisitos

Instalação

Estrutura do Banco de Dados

Configuração

Guia de Uso

1. Inicializando o SDK

2. Autenticação de Usuários (`authenticate`)

3. Verificação de Autenticação (`authenticated` e `checkSessionToken`)

4. Controle de Acesso a Sistemas (`access`)

5. Autorização de Permissões (`authorizated`)

6. Encerramento de Sessão / Logoff (`unauthenticate`)

Tratamento de Exceções

Enumerações de Status

Exemplo Prático (Web Demo)

Testes e Qualidade de Código

Detalhamento dos Scripts

Licença

everton3x / cerbero-sdk

Package info

Security

Statistics

README

Sumário

Recursos

Requisitos

Instalação

Estrutura do Banco de Dados

Configuração

Guia de Uso

1. Inicializando o SDK

2. Autenticação de Usuários (authenticate)

3. Verificação de Autenticação (authenticated e checkSessionToken)

4. Controle de Acesso a Sistemas (access)

5. Autorização de Permissões (authorizated)

6. Encerramento de Sessão / Logoff (unauthenticate)

Tratamento de Exceções

Enumerações de Status

Exemplo Prático (Web Demo)

Testes e Qualidade de Código

Detalhamento dos Scripts

Licença

2. Autenticação de Usuários (`authenticate`)

3. Verificação de Autenticação (`authenticated` e `checkSessionToken`)

4. Controle de Acesso a Sistemas (`access`)

5. Autorização de Permissões (`authorizated`)

6. Encerramento de Sessão / Logoff (`unauthenticate`)