README

Horse RBAC Middleware

Middleware de controle de acesso baseado em funções (RBAC) e escopos para o framework Horse.

Projetado para simplificar a autorização de rotas em APIs Delphi e Lazarus, permitindo a checagem de permissões e escopos granulares de forma simples e declarativa. O middleware lê as permissões do usuário a partir das Claims do JWT decodificado e gerencia o controle de acesso por rota.

⚙️ Instalação

A instalação é feita de forma simples através do gerenciador de pacotes boss:

boss install horse-rbac

⚡️ Como usar

1. Configure e Proteja suas Rotas

Basta declarar a unit Horse.RBAC e injetar o middleware nas rotas desejadas. O middleware lê o payload do token JWT diretamente de Req.Session (injetado previamente por qualquer middleware de autenticação, como o horse-jwt).

uses
  Horse,
  Horse.JWT,
  Horse.RBAC;

begin
  // Middleware global de autenticação JWT
  THorse.Use(HorseJWT('sua_chave_secreta_jwt'));

  // Rota protegida: Exige a permissão 'pedidos:read' (Lógica OR por padrão)
  THorse.Get('/pedidos', [RBAC(['pedidos:read'])],
    procedure(Req: THorseRequest; Res: THorseResponse)
    begin
      Res.Send('Acesso concedido aos pedidos!');
    end);

  THorse.Listen(9000);
end.

2. Configure a Lógica de Permissões (Parâmetros)

O middleware é inicializado através da função RBAC:

function RBAC(const APermissions: array of string; const AClaimName: string = 'permissions'; const AVerifyAll: Boolean = False): THorseCallback;

• APermissions: Array de strings contendo os escopos/permissões granulares necessários para acessar a rota (ex: ['pedidos:read'], ['pedidos:write', 'entidades:write']).
• AClaimName: Nome da chave (claim) dentro do objeto JSON da sessão onde estão listadas as permissões do usuário. O padrão é 'permissions'.
• AVerifyAll: Lógica de checagem quando há múltiplos escopos requeridos:
  • False (Padrão - Lógica OR): O usuário precisa possuir pelo menos uma das permissões informadas no array para ter acesso concedido.
  • True (Lógica AND): O usuário precisa possuir todas as permissões listadas no array para ter acesso concedido.

📦 Formato Esperado da Claim no JWT

O middleware processa exclusivamente a claim do JWT contendo as permissões no formato de JSON Array de Strings:

{
  "sub": "1234567890",
  "name": "João Silva",
  "permissions": [
    "pedidos:read",
    "pedidos:write",
    "entidades:write"
  ]
}

🛑 Tratamento de Erros e Interrupção

Em conformidade com o ecossistema do Horse:

• Caso a sessão JWT não seja encontrada em Req.Session (usuário não autenticado), o middleware retorna status 401 Unauthorized e interrompe o pipeline levantando a exceção EHorseCallbackInterrupted.
• Caso as permissões do usuário sejam insuficientes ou a claim especificada não seja um JSON Array válido, o middleware retorna status 403 Forbidden e interrompe a requisição imediatamente de forma limpa.

📄 Integração com o GBSwagger

O horse-rbac integra-se perfeitamente com a documentação automática de segurança do GBSwagger.

Configuração do Esquema no Swagger:

  GBSwagger
    .Register
      .Security
        .Bearer('Bearer')
          .Description('Autenticação baseada em token JWT.');

Anotação nos Controllers:

type
  [SwagPath('pedidos', 'Pedidos')]
  TPedidosController = class
  public
    [SwagGET('Listar pedidos')]
    [SwagSecurity('Bearer', ['pedidos:read'])] // <-- Associa o escopo do Swagger
    procedure Get(Req: THorseRequest; Res: THorseResponse);
  end;

💻 Compatibilidade

• Delphi XE7 e superiores.
• Lazarus / Free Pascal (FPC) (compatibilidade garantida via diretivas de compilação utilizando fpjson).
• Desenvolvido sob princípios Clean Code, SOLID e thread-safe.

📄 Licença

Este projeto está licenciado sob a Apache License 2.0.