Catálogo de permissões e papéis do sistema — API

Quatro rotas de leitura que expõem o catálogo fixo de permissões do backend e os papéis de sistema canônicos. Servem para montar telas de administração de papéis/políticas (ex.: um seletor de permissões) e para qualquer client que precise decodificar um bitmask de permissão em nomes legíveis.

Funcionamento

• GET /authorization/permissions devolve a lista completa de permissões atribuíveis (PermissionCatalog.assignable() — exclui as marcadas como retired), cada uma com id, name, resource/resource_label, action/action_label, bit_position e description.
• GET /authorization/resources devolve o mesmo catálogo agrupado por resource (ex.: todas as permissões de exam num único item com sua lista de permissões).
• GET /authorization/system-roles devolve os nove papéis de sistema canônicos (IdentitySystemRoleCatalog.reconciled()) casados com o registro persistido de cada um (id, legacy_profile_id, role_key, display_name, permissions). Se um papel de sistema esperado não estiver persistido, a rota lança erro interno (Canonical Identity system role is not persisted) — isso indicaria que o bootstrap do catálogo (BootstrapIdentityAuthorizationCatalogService, rodado uma vez no onApplicationBootstrap) não rodou ou falhou.
• GET /authorization/permission-bit-catalog devolve só name + bit_position de todo o catálogo (PermissionCatalog.all() — inclui permissões retired, ordenado por bit_position), sem exigir nenhuma permissão RBAC — qualquer usuário autenticado pode ler o dicionário de bits. Confirmado em teste (identity-permission-bit-catalog.e2e.spec.ts): o mesmo ator recebe 403 ao chamar GET /authorization/permissions (que exige permission:read) mas 200 aqui.

Endpoints

Método	Rota	Descrição
GET	/v1/authorization/permissions	Lista o catálogo de permissões atribuíveis
GET	/v1/authorization/resources	Lista permissões atribuíveis agrupadas por recurso
GET	/v1/authorization/system-roles	Lista os nove papéis de sistema canônicos
GET	/v1/authorization/permission-bit-catalog	Lista todo nome de permissão com sua posição de bit

Versão: v1

Swagger: Identity — Authorization catalog · readPermissionBitCatalog · Rota (Dev): http://localhost:3000/v1/authorization/permissions

Permissões

Rota	Guards	Permissão exigida (escopo global-catalog)
GET /authorization/permissions	IdentityOAuthAccessTokenGuard, AuthorizationGuard	permission:read, match: all
GET /authorization/resources	idem	permission:read, match: all
GET /authorization/system-roles	idem	role:read, match: all
GET /authorization/permission-bit-catalog	somente IdentityOAuthAccessTokenGuard	nenhuma — qualquer sessão autenticada

Headers

Header	Obrigatório	Descrição
Authorization	Sim	Bearer <access_token>

Path parameters

Nenhum.

Query parameters

Nenhum.

Body

Nenhum (todas as rotas são GET).

Response

GET /permissions — 200:

json
{
  "data": {
    "items": [
      {
        "id": "b7c5...uuid",
        "name": "exam:read",
        "resource": "exam",
        "resource_label": "Exames",
        "action": "read",
        "action_label": "Visualizar",
        "bit_position": 0,
        "description": "Visualizar exames"
      }
    ]
  }
}

GET /resources — 200:

json
{ "data": { "items": [ { "resource": "exam", "resource_label": "Exames", "permissions": [ /* IdentityPermissionCatalogResponse[] */ ] } ] } }

GET /system-roles — 200:

json
{
  "data": {
    "items": [
      {
        "id": "3f2a...uuid",
        "legacy_profile_id": 6,
        "role_key": "read_only",
        "display_name": "Read only",
        "permissions": ["exam:read", "report:read", "user:read", "unit:read", "group:read", "tenant:read"]
      }
    ]
  }
}

GET /permission-bit-catalog — 200:

json
{ "data": { "items": [ { "name": "exam:read", "bit_position": 0 }, { "name": "sla:read", "bit_position": 102 } ] } }

Mapa de campos

Campo	Tipo	Onde aparece	Descrição
name	string	permissions, resources, system-roles.permissions, permission-bit-catalog	Nome canônico recurso:ação (ex.: exam:read)
resource / resource_label	string	permissions, resources	Recurso e seu rótulo traduzido
action / action_label	string	permissions	Ação e seu rótulo traduzido
bit_position	integer	permissions, permission-bit-catalog	Posição do bit no bitmask — fixa, nunca reaproveitada mesmo se a permissão for retired
description	string	permissions	Descrição traduzida da permissão
legacy_profile_id	integer (1–9)	system-roles	ID numérico do perfil correspondente no sistema legado
role_key	string	system-roles	Chave estável do papel (administrator, manager, doctor, technician, resident, read_only, typist, requestor, financial)
permissions	string[]	system-roles	Nomes de permissão do papel de sistema

Erros

Classe de erro	Status	Quando ocorre
UnauthenticatedError (IDENTITY_INVALID_OAUTH_ACCESS_TOKEN)	401	token ausente/inválido/expirado, em qualquer das quatro rotas
ForbiddenAction (AUTHORIZATION_CLAIM_UNAVAILABLE)	403	claim de autorização indisponível (não se aplica ao permission-bit-catalog)
ForbiddenAction (insuficiente)	403	ator sem permission:read/role:read no catálogo global (não se aplica ao permission-bit-catalog)
Erro interno (sem errorCode de negócio)	500	um papel de sistema esperado não está persistido (GET /system-roles) — indica bootstrap do catálogo não executado

Regras de negócio

ID	Regra	Comportamento esperado
RN-01	permission-bit-catalog não exige nenhuma permissão RBAC	qualquer usuário autenticado lê o dicionário completo de bits, incluindo permissões retired
RN-02	permissions/resources só listam permissões atribuíveis	permissões retired aparecem em permission-bit-catalog mas não em permissions/resources — o bit nunca é reaproveitado por outra permissão
RN-03	Papéis de sistema são semeados no boot, não por esta API	não há rota de escrita para papéis system neste módulo; a lista vem de IdentitySystemRoleCatalog.reconciled() casada com o registro persistido
RN-04	O papel manager reconciliado exclui report:sign do catálogo atribuível completo	assinatura de laudo é ato clínico; decisão documentada em código (22/09/2026)

Compliance

A confirmar — responsável: time de Identity; data: 24/09/2026. Nenhuma anotação de compliance (LGPD/HIPAA/ANVISA) foi encontrada no código destas quatro rotas. Os cartões do Bitrix (funil 562) descrevem exigências de minimização e least-privilege para o sistema legado equivalente, mas sem confirmação no código atual — ver nota na visão geral do módulo.

Variáveis de ambiente

Nenhuma variável de ambiente é consumida diretamente por estas rotas.

Tempo médio de resposta

A confirmar — responsável: time de Identity; data: 24/09/2026. Sem medição publicada.

Requisitos não funcionais

Requisito	Definição
Idempotência	Sim (leitura pura, sem efeito colateral)
Paginação	Não — as quatro rotas devolvem a lista completa (o catálogo é pequeno e estático)
Rate limit	Não identificado
Cache	Não identificado cache de aplicação nestas rotas (o catálogo já vem de constantes em memória)
Auditoria	Não — rotas de leitura, sem evento de auditoria

Relacionado

• 📂 Módulo: Authorization
• 🔁 Usado por: Papéis (seleção de permissões ao criar/editar um papel customizado) e Políticas de autorização (seleção da permissão-alvo de uma política)