Capabilities e Controle de Acesso
Lista das capabilities próprias do local_helico e as regras que toda rota nova precisa seguir para não expor dado de um aluno a outro.
Fonte da verdade
As definições ficam em
db/access.phpe as descrições curtas (tela de papéis do Moodle) emlang/en/local_helico.php. Este documento explica o uso; se houver divergência, vale o código.
Capabilities do plugin
| Capability | Tipo | Padrão | Para quê | Usada em |
|---|---|---|---|---|
local/helico:devtools |
read | manager | Telas DEV (lifecycle inspector e diagnóstico). Expõe dados de matrícula (RISK_PERSONAL). |
Telas admin DEV; também libera áreas de arquivo de conteúdo no pluginfile_access_service |
local/helico:viewchangereport |
read | manager | Ver o relatório de alterações do conteúdo vindo do Word, por Unidade. | Controllers do relatório de alterações |
local/helico:managechangereport |
write | manager | Aprovar ou arquivar itens do relatório de alterações. | Controllers do relatório; libera file_word_* no pluginfile_access_service |
local/helico:correctexams |
write | manager | Corrigir Simulado Escrito como Tutor: fila, detalhe, assumir, submeter correção e disparar a IA. RISK_PERSONAL. |
admin/exam_correction_controller (preHandle); libera provas e PDFs de IA no pluginfile_access_service |
Capabilities do core do Moodle que o plugin também exige:
| Capability | Onde | Efeito |
|---|---|---|
moodle/user:viewalldetails |
external::get_produtos |
Consultar os produtos de outro usuário. Sem ela, só os do próprio usuário. |
Administrador do site
O administrador do Moodle passa em qualquer verificação de capability, inclusive nas do plugin e mesmo antes de a capability existir no banco. Papéis de operação (Tutor, Gestor Pedagógico) precisam receber a capability explicitamente.
Quem deve receber o quê em produção
| Papel | Capabilities | Observação |
|---|---|---|
| Tutor | local/helico:correctexams |
Obrigatório para o Tutor usar a correção. Sem isso, só manager e admin acessam. |
| Gestor Pedagógico | local/helico:viewchangereport, local/helico:managechangereport |
Aprova e arquiva itens do relatório. |
| Equipe técnica | local/helico:devtools |
Só onde as telas DEV forem necessárias. |
| Aluno | nenhuma | O acesso do aluno é por dono do recurso, não por capability (ver abaixo). |
Capability nova só existe no banco depois do release que sobe $plugin->version (feito pelo release-please). Depois do release, atribua o papel.
Regra de guarda: dado de usuário
Toda rota que recebe o id de um recurso do usuário ({enrolment_id}, {slot_id}, {submission_id}…) precisa conferir se o recurso pertence ao usuário da sessão. Sem isso, um aluno troca o número na URL e lê ou altera dados de outro (IDOR, middag-io/docker-moodle-helico#86).
| Situação | O que fazer |
|---|---|
Rota com {enrolment_id} |
Declare #[Middleware(enrolment_ownership_middleware::class)] na classe do controller. Responde 404 enrolment_not_found para matrícula alheia ou inexistente. |
Rota com {slot_id} junto de {enrolment_id} |
O mesmo middleware confere que o slot pertence ao plano da matrícula (404 slot_not_found). |
Rota de Tutor ou Gestor (platform/controller/admin/) |
preHandle() com setRequireLogin() e setRequireCapabilities([...]). |
Outro id de recurso ({offer_id}, {submission_id}…) |
Confira o dono no service e registre a exceção, com motivo, em platform_ownership_guard_test::OTHER_ID_EXCEPTIONS. |
Arquivo servido por pluginfile |
Inclua a área em pluginfile_access_service::AREA_POLICIES com a política certa. Área fora da lista é negada. |
Função externa (web service) com userid |
Não confie no userid do cliente: use o usuário da sessão (user_support::get_current_user_id()) e exija capability para consultar outro. |
Para ler o usuário da sessão use user_support::get_current_user_id() e, para o estado de login, auth_support::is_logged_in() / is_guest(), em vez de $USER direto.
O teste falha de propósito
tests/regression/platform_ownership_guard_test.phpfalha quando um controller com{enrolment_id}não tem guarda, quando um controller admin não exige login e capability, ou quando um id de recurso não tem guarda nem exceção justificada. Se ele falhou, a rota está aberta: proteja-a, não aumente a lista de exceções.
Como verificar uma rota
Com duas contas de teste (por exemplo demo01 e demo02), chame a rota pelo HTTP, passando pelo roteador, com o token da primeira e o id de um recurso da segunda. O esperado é 404 (ou 403) sem nenhum dado. Repita com o id da própria conta e espere a resposta normal.
Chamar o método do controller direto em teste não prova nada: o guarda roda no roteador, antes da ação.