Skip to main content

ADR-0003 — Controle de Acesso (RBAC com Escopo Hierárquico)

Status​

Aprovado

Contexto​

O sistema EBDbe opera dentro de uma estrutura organizacional hierárquica composta por:

  • Ministério
  • Árvore de igrejas autorrelacionadas (OrganizationalUnit com parent_unit_id)

Além disso, existem papéis funcionais distintos dentro da Escola Bíblica Dominical (EBD), como:

  • Pastor
  • Superintendente
  • Secretaria
  • Professor
  • Monitor
  • Aluno

O modelo de controle de acesso deve considerar:

  1. Papel do usuário (função)
  2. Unidade organizacional vinculada
  3. Nível hierárquico de visibilidade

Um modelo simples de RBAC tradicional (baseado apenas em papel) não é suficiente.

Decisão​

O sistema adotará modelo de controle de acesso baseado em:

RBAC (Role-Based Access Control) com Escopo Hierárquico Organizacional.

O acesso será determinado por:

Permissão = Papel + Escopo Organizacional

1. Componentes do Modelo​

1.1 Papel (Role)​

Define o que o usuário pode fazer.

Papéis, com nível de operação (menor = mais poder):

PapelNívelDescrição
PLATFORM_ADMIN-1Administrador global da plataforma (cross-tenant, auditado)
MINISTRY_ADMIN0Administrador do ministério
MINISTERIAL_EBD_SUPERVISOR1Supervisor ministerial da EBD
PRESIDENT_PASTOR1Pastor presidente
ASSISTANT_MINISTERIAL_PASTOR1Pastor auxiliar ministerial
LOCAL_SECRETARY2-3Secretário(a) da igreja local
EBD_SUPERINTENDENT2-3Superintendente da EBD
ASSISTANT_LOCAL_PASTOR2-3Pastor auxiliar local
LOCAL_PASTOR2-3Pastor local
EBD_SECRETARY4Secretário(a) da EBD
EBD_TEACHER5Professor da EBD
EBD_ASSISTENT6Assistente de classe
CHURCH_LEADER6Líder na igreja
EBD_STUDENT7Aluno da EBD
MEMBER7Membro
CHURCH_WORKER7Obreiro da igreja
NONE—Nenhum

Os papéis determinam permissões funcionais. Um usuário pode possuir múltiplos papéis (via RoleAssignment), cada um com status de aprovação (APPROVED | REJECTED | DECLARED | PENDING). Apenas papéis com status APPROVED são considerados válidos para autorização.

Para PLATFORM_ADMIN, o escopo é global de plataforma, porém ações em dados ministeriais exigem target_ministry_id explícito e auditoria obrigatória (ADR-0012).

1.2 Tipo de Acesso (AccessType)​

Para cada combinação Papel + Recurso/Funcionalidade, define-se o tipo de operação permitida:

  • READ — visualização
  • INSERT_UPDATE — criação e edição
  • DELETE — exclusão
  • NONE — sem acesso

A validação no backend verificará Papel + AccessType + Escopo Organizacional.

1.3 Escopo Organizacional (Scope)​

Define onde o usuário pode atuar.

O escopo estará vinculado a (conforme entidades do ADR-0005):

  • ministry_id
  • unit_id (referência a OrganizationalUnit)
  • relação hierárquica entre unidade do ator e unidade alvo (SAME | ANCESTOR | DESCENDANT | UNRELATED)
  • host/domain da requisição, quando aplicável (resolução de tenant)

Exemplo:

Um professor (EBD_TEACHER) vinculado a uma unidade:

  • Pode registrar aulas (Lesson) apenas daquela unidade
  • Não pode visualizar dados de outra unidade fora do seu ramo hierárquico autorizado
  • Pode visualizar apenas sua própria ClassGroup

2. Regras Fundamentais​

  1. Toda requisição será validada no backend.
  2. O frontend nunca será considerado autoridade de permissão.
  3. O backend verificará:
    • Papel (Role)
    • ministry_id
    • unit_id e relação hierárquica entre unidade de origem e unidade-alvo
  4. O usuário nunca poderá acessar dados fora do seu escopo.
  5. Em operações cross-tenant, somente PLATFORM_ADMIN pode atuar, sempre com target_ministry_id explícito e logging de auditoria.
  6. Aprovações de cadastro/atribuição por secretarias só podem ocorrer em unidades sob seu alcance hierárquico ("abaixo dela"), conforme papel e status APPROVED.

3. Hierarquia de Visibilidade​

Regras gerais:

  • Ministério: visão global de todas as unidades vinculadas.
  • Unidade local: visão do próprio contexto e, quando autorizado por papel, das unidades descendentes.
  • Unidade descendente: não acessa unidades ancestrais ou ramos paralelos sem autorização explícita.

Não haverá acesso lateral entre ramos não relacionados.

4. Modelo Conceitual Simplificado​

User (conforme ADR-0005): ├── ministry_id ├── unit_id ├── name ├── alias_name ├── email ├── status └── roles[] (RoleAssignment) ├── role_id ├── role_status (APPROVED | REJECTED | DECLARED | PENDING) └── last_action_date

Para usuários com escopo ministerial (ex.: MINISTRY_ADMIN), unit_id pode ser nulo.

As permissões serão avaliadas em Cloud Functions, considerando Papel (apenas APPROVED) + AccessType + Escopo.

5. Autenticação​

A autenticação será realizada via Firebase Authentication.

As informações de papel e escopo serão armazenadas:

  • No Firestore
  • Opcionalmente em Custom Claims do Firebase

A validação final sempre ocorrerá no backend.

6. Princípios de Segurança​

  • Princípio do menor privilégio
  • Isolamento por escopo
  • Validação obrigatória no backend
  • Logs de auditoria para ações sensíveis

Consequências​

  • Todas as Cloud Functions deverão validar papel e escopo.
  • O modelo de dados deve conter ministry_id e unit_id.
  • Permissões não poderão ser decididas apenas na interface.
  • Alterações no modelo de acesso exigirão novo ADR.
  • O backend deve distinguir escopo ministerial de escopo global de plataforma.
  • Referência complementar: ADR-0012.
Last updated on