@apipass/cerbos-pep

English | Português

English

Description

@apipass/cerbos-pep is a NestJS utility designed to simplify integration with Cerbos, an open-source authorization layer. This package provides a PEP (Policy Enforcement Point) through a NestJS Interceptor that automatically validates permissions against a Cerbos PDP (Policy Decision Point).

How it works

The interceptor intercepts incoming HTTP requests, extracts principal information (role and account id) from the request headers (role and account_id), and checks if the principal is allowed to perform specific actions on a resource defined via the @CerbosPermission decorator.

Usage Example

1. Import CerbosModule

Register the CerbosModule in your AppModule:

import { CerbosModule } from '@apipass/cerbos-pep';

@Module({
  imports: [
    CerbosModule.register({
      url: process.env.CERBOS_PDP_URL ?? 'http://127.0.0.1:3592', // Cerbos PDP URL
    }),
  ],
})
export class AppModule {}

2. Apply the Interceptor

You can apply the CerbosInterceptor globally, at the controller level, or per-route:

import { CerbosInterceptor } from '@apipass/cerbos-pep';
import { UseInterceptors } from '@nestjs/common';

@UseInterceptors(CerbosInterceptor)
@Controller('orders')
export class OrdersController {}

3. Define Permissions

Use the @CerbosPermission decorator to protect your routes:

import { CerbosPermission } from '@apipass/cerbos-pep';

@Get(':id')
@CerbosPermission({
  resource: {
    kind: 'order',
  },
  actions: ['read'],
})
async getOrder(@Param('id') id: string) {
  return this.ordersService.findOne(id);
}

Note: The interceptor expects role and account_id headers to be present in the request.

Português

Descrição

O @apipass/cerbos-pep é um utilitário para NestJS projetado para simplificar a integração com o Cerbos, uma camada de autorização de código aberto. Este pacote fornece um PEP (Policy Enforcement Point) por meio de um Interceptor do NestJS que valida automaticamente as permissões em um Cerbos PDP (Policy Decision Point).

Como funciona

O interceptor intercepta as requisições HTTP, extrai as informações do principal (role e id da conta) dos cabeçalhos da requisição (role e account_id) e verifica se o principal tem permissão para realizar ações específicas em um recurso definido através do decorador @CerbosPermission.

Exemplo de Utilização

1. Importar o CerbosModule

Registre o CerbosModule no seu AppModule:

import { CerbosModule } from '@apipass/cerbos-pep';

@Module({
  imports: [
    CerbosModule.register({
      url: 'http://localhost:3592', // URL do Cerbos PDP
    }),
  ],
})
export class AppModule {}

2. Aplicar o Interceptor

Você pode aplicar o CerbosInterceptor globalmente, no nível do controller ou por rota:

import { CerbosInterceptor } from '@apipass/cerbos-pep';
import { UseInterceptors } from '@nestjs/common';

@UseInterceptors(CerbosInterceptor)
@Controller('orders')
export class OrdersController {}

3. Definir Permissões

Use o decorador @CerbosPermission para proteger suas rotas:

import { CerbosPermission } from '@apipass/cerbos-pep';

@Get(':id')
@CerbosPermission({
  resource: {
    kind: 'order',
  },
  actions: ['read'],
})
async getOrder(@Param('id') id: string) {
  return this.ordersService.findOne(id);
}

Nota: O interceptor espera que os headers role e account_id estejam presentes na requisição.