README

Biblioteca PHP para autenticação e autorização com o serviço Miau da Eduzz.

Compatibilidade

Pre-Requisito

• É necessário o uso do APCU nos ambientes para carregamento de cache em memória.

• Caso APCU não esteja disponível, o sistema utiliza cache em memória estática (fallback). Mais detalhes: https://www.php.net/manual/pt_BR/book.apcu.php

• PHP: 7.3+ | 8.0+

• Laravel: 5.5+ | 6.0+ | 7.0+ | 8.0+ | 9.0+ | 10.0+

• Guzzle: 6.0+ | 7.0+

• Firebase JWT: 5.0+ | 6.0+

Instalação

Via Composer:

composer require eduzz-miau/miau-auth-lib

Configuração

Laravel

Laravel 5.6+: Service Provider é registrado automaticamente.

Laravel 5.5: Adicione manualmente no config/app.php:

'providers' => [
    // ...existing providers...
    EduzzMiau\Miau\MiauServiceProvider::class,
],

Publique o arquivo de configuração:

php artisan vendor:publish --provider="EduzzMiau\Miau\MiauServiceProvider"

Configure as variáveis no seu .env:

MIAU_API_URL=https://api.miau.eduzz.com
MIAU_APP_SECRET=miau_v1_seu_secret_aqui
MIAU_ENVIRONMENT=development
MIAU_TIMEOUT=30
MIAU_VERIFY_SSL=true

PHP Puro

<?php
require_once 'vendor/autoload.php';

use EduzzMiau\Miau\Miau;

$config = [
    'api_url' => 'https://api.miau.eduzz.com',
    'app_secret' => 'miau_v1_seu_secret_aqui',
    'environment' => 'development'
];

$miau = new Miau($config);

Uso

Laravel Middleware

O middleware é registrado automaticamente com o alias miau.

Use em suas rotas:

Route::middleware('miau')->group(function () {
    Route::get('/users', 'UserController@index');
    Route::post('/users', 'UserController@store');
});

// Ou em rotas individuais
Route::get('/protected', 'Controller@method')->middleware('miau');

Usando Facade (Laravel)

use EduzzMiau\Miau\Facades\Miau;

try {
    $authHeader = $request->header('Authorization');
    $token = $authHeader && strpos($authHeader, 'Bearer ') === 0 
        ? substr($authHeader, 7) 
        : null;
    
    if (!$token) {
        return response()->json(['error' => 'Token not provided'], 401);
    }
    
    $clientToken = Miau::verifyToken($token);
    
    $hasPermission = Miau::validatePermissions(
        $clientToken, 
        $request->method(), 
        $request->path()
    );
    
    if ($hasPermission) {
        $appInfo = $request->get('miau_application');
        $metadata = $request->get('miau_metadata');
        
        return response()->json([
            'message' => 'Access granted',
            'app' => $appInfo,
            'metadata' => $metadata
        ]);
    } else {
        return response()->json(['error' => 'Insufficient permissions'], 403);
    }
} catch (\EduzzMiau\Miau\Exceptions\MiauException $e) {
    return response()->json(['error' => $e->getMessage()], 401);
}

Uso Direto (PHP Puro)

use EduzzMiau\Miau\Miau;

$miau = new Miau($config);

try {
    $authHeader = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
    $token = '';
    
    if (strpos($authHeader, 'Bearer ') === 0) {
        $token = substr($authHeader, 7);
    }
    
    if (!$token) {
        http_response_code(401);
        echo json_encode(['error' => 'Token not provided']);
        exit;
    }
    
    $clientToken = $miau->verifyToken($token);
    
    $hasPermission = $miau->validatePermissions(
        $clientToken, 
        $_SERVER['REQUEST_METHOD'], 
        parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH)
    );
    
    if ($hasPermission) {
        echo json_encode([
            'message' => 'Access granted',
            'app_id' => $clientToken['application']['id']
        ]);
    } else {
        http_response_code(403);
        echo json_encode(['error' => 'Insufficient permissions']);
    }
} catch (\EduzzMiau\Miau\Exceptions\MiauException $e) {
    http_response_code(401);
    echo json_encode(['error' => $e->getMessage()]);
}

Middleware com Fallback

Route::middleware('miau:App\Http\Middleware\AuthMiddleware')->group(function () {
    Route::get('/optional-auth', 'Controller@method');
});

Exceções

A biblioteca fornece as seguintes exceções:

• MiauException - Exceção base
• InvalidConfigurationException - Configuração inválida
• UnauthorizedException - Token inválido ou expirado
• ForbiddenException - Sem permissão para acessar o recurso
• HttpError - Erro de comunicação HTTP

Exemplos de Resposta

Sucesso

{
  "miau_application": {
    "id": "app_123",
    "name": "Minha Aplicação"
  },
  "miau_metadata": {
    "custom_field": "value"
  }
}

Erro

{
  "error": "Unauthorized",
  "message": "Token verification failed"
}

Desenvolvimento Local

Para contribuir:

git clone https://github.com/dedecamp06/auth-miau.git
cd auth-jwt-miau
composer install

Estrutura do Projeto

src/
├── Miau.php                 # Classe principal
├── MiauServiceProvider.php  # Service Provider Laravel
├── Facades/
│   └── Miau.php            # Facade Laravel
├── Middleware/
│   └── MiauMiddleware.php  # Middleware Laravel
└── Exceptions/
    └── MiauException.php   # Exceções customizadas

Funcionalidades

• ✅ Verificação JWT com chaves públicas JWKS
• ✅ Validação de permissões com suporte a wildcards
• ✅ Cache inteligente de chaves e permissões
• ✅ Middleware Laravel com fallback
• ✅ Suporte a múltiplos ambientes (dev/staging/prod)
• ✅ Compatível PHP 7.3+ e Laravel 5.5+
• ✅ Validação SSL configurável
• ✅ Tratamento de erros customizado

Compatibilidade Testada

Laravel 5.5 + PHP 7.3

# Testado e funcionando
"laravel/framework": "5.5.*"
"php": "7.3"

Versões Suportadas

• PHP: 7.3, 7.4, 8.0, 8.1, 8.2, 8.3
• Laravel: 5.5, 6.x, 7.x, 8.x, 9.x, 10.x, 11.x
• Guzzle: 6.x, 7.x
• Firebase JWT: 5.x, 6.x

Versionamento

Use Semantic Versioning:

• v1.0.0 - Primeira versão estável
• v1.0.1 - Correção de bugs
• v1.1.0 - Nova funcionalidade
• v2.0.0 - Breaking changes

# Para nova versão
git tag v1.1.0
git push origin v1.1.0

Contribuição

1. Faça um fork do projeto
2. Crie uma branch (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças (git commit -am 'Adiciona nova funcionalidade')
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

Licença

Este projeto está licenciado sob a Licença MIT.