Autorização e permissões

Como o PermissionGuard valida resource + scope contra as permissões do Keycloak.

Este guard não está ativo hoje

O PermissionGuard descrito nesta página está importado mas nunca registrado (APP_GUARD comentado em app.module.ts) — o @Permissions(...) continua em todo controller, mas não é avaliado por ninguém. Quem decide autorização de verdade hoje é o RolesGuard (persona por tenant + roles de exceção), descrito em Autenticação e no mapa MAPA-ACESSO-ENDPOINTS.md do backend. Esta página fica como referência do Resource/Scope (ainda existem no código) e para o dia em que o guard for religado — não use como descrição do comportamento atual da API.

A autorização seria feita por um PermissionGuard global (registrado como APP_GUARD) — hoje não registrado, ver aviso acima. Cada rota protegida declara o par resource + scope que exigiria, via decorator:

@Permissions(Resource.Users, Scope.Create)
@Post()
async handle(@Body() body: CreateUserBody) { /* ... */ }

Como o guard decide

Regras, na ordem:

Rota sem @Permissions → liberada.
isSuperAdmin (hoje vem de User.type === 'Global' no banco, não de role do Keycloak) → bypass total.
Sem nenhuma permissão → 403 Forbidden (NOT_ALLOWED).
Caso contrário, exige uma permissão cujo rsname seja igual ao resource e cujos scopes contenham o scope da rota.

Resources

Definidos em Resource (src/domain/auth/application/enums/resource.enum.ts). Recursos de coleção e recursos "por id" são distintos:

Resource	Valor (`rsname`)	Usado em
`Resource.Customers`	`resource:customers`	criar / listar customers
`Resource.CustomersById`	`resource:customers_id`	obter / editar / excluir por id
`Resource.Tenants`	`resource:tenants`	criar / listar tenants
`Resource.TenantsById`	`resource:tenants_id`	obter / editar / excluir por id
`Resource.Apps`	`resource:apps`	criar / listar apps
`Resource.AppsById`	`resource:apps_id`	obter / editar / excluir por id
`Resource.Users`	`resource:users`	criar / listar usuários
`Resource.UsersById`	`resource:users_id`	obter / editar / excluir por id
`Resource.Cooperatives`	`resource:cooperatives`	listar cooperativas
`Resource.AuditLogs`	`resources:audit-logs`	logs de auditoria

Scopes

Definidos em Scope:

Scope	Valor	Operação HTTP típica
`Scope.Create`	`create`	`POST`
`Scope.Read`	`read`	`GET`
`Scope.Update`	`update`	`PUT`
`Scope.Delete`	`delete`	`DELETE`

Os valores de rsname e scopes corresponderiam à modelagem de autorização (UMA) configurada no Keycloak, se o guard estivesse ativo (ver aviso no topo da página). Hoje esse contrato não é verificado em nenhuma request — a autorização real é o RolesGuard.

Como o guard decide

Resources

Scopes

On this page