Roteamento & Middlewares v3 HEADLESS

A v3 centraliza a API em routes/api.php, com isenção de CSRF por grupo e middlewares descobertos por alias.

Rotas API oficiais

use MUCRM\engine\support\facades\uri;
use MUCRM\http\handlers\api\auth_handler;

uri::group(['prefix' => 'api', 'without_csrf' => true], function () {
    uri::post('/login', [auth_handler::class, 'login']);

    uri::group(['middleware' => ['auth:api']], function () {
        uri::post('/me', [auth_handler::class, 'me']);
        uri::post('/logout', [auth_handler::class, 'logout']);
    });
});

Método	Rota	Auth	Descrição
`POST`	`/api/login`	—	Login → `{ success, token }`
`POST`	`/api/me`	`auth:api`	Usuário autenticado
`POST`	`/api/logout`	`auth:api`	Revoga token `login`

⚠️Sempre without_csrf em APIs

Launchers, apps, bots e SPAs não enviam token CSRF de sessão. Use o atributo no grupo ou ->without_csrf() na rota.

Isenção CSRF (`without_csrf`)

Por grupo (recomendado)

uri::group(['prefix' => 'api', 'without_csrf' => true], function () {
    uri::post('/login', [auth_handler::class, 'login']);
    uri::get('/posts', [post_api_handler::class, 'index']);
});

Por rota individual

uri::post('/webhook/stripe', [payment_webhook_handler::class, 'handle'])
    ->without_csrf()
    ->name('webhooks.stripe');

Método	Escopo	Cenário
`'without_csrf' => true`	Grupo	APIs REST, apps, integrações
`->without_csrf()`	Rota	Webhooks, callbacks de pagamento

Middlewares por alias

Crie a classe em app/Http/Middlewares/ com $alias. O Engine faz auto-discover — não edite o AuthServiceProvider do cliente.

namespace MUCRM\http\middlewares;

use MUCRM\engine\http\middleware\middleware;

class meu_guard extends middleware
{
    protected string $alias = 'meu-guard';

    public function handle(): bool
    {
        return true;
    }
}

Uso:

uri::group(['middleware' => ['meu-guard', 'auth:api']], function () {
    // ...
});

Aliases oficiais

Alias	Função
`api.allow`	Allowlist `auth.allowed` — automático em `/api/*`
`auth:api`	Bearer Token
`admin`	Sessão painel
`user`	Sessão site

FQCN (AdminAuth::class) continua válido. Alias desconhecido lança RuntimeException.

Allowlist de origem

Em bootstrap/config/auth.php:

'allowed' => ['*'], // aberto

// ou lista (basta 1 item bater):
'allowed' => [
    '203.0.113.10',
    'meusite.com',
    'https://app.amigo.com',
],

Negado → 403 { "error": "Origem não autorizada." }

Parâmetros tipados

uri::get('/profile/{id:int}', [ProfileController::class, 'show'])
    ->name('user.profile.show');