Escopo por app para Editores: gerenciar usuários/grupos apenas dos apps a que têm acesso (revisita o #517)

[milkway]

Pedido do lead (lista 2026-07): "Permitir que o editor gerencie usrs e grupos APENAS dos apps que possui acesso [por ora, resolver na camada de negócio]."

Contexto

O #517 decidiu manter RBAC por papel (Editor opera o catálogo inteiro; sem ownership por app), com a nota explícita "revisitar se muitos editores de times diferentes dividirem um catálogo". Este pedido é essa demanda chegando — reabrimos a discussão.

Hoje, além disso, Usuários/Grupos são Admin-only (can_access_section): o pedido implica delegar gestão de pessoas a Editores, com escopo.

Modelo proposto (para discussão)

• O escopo natural já existe: grupos. Um Editor enxerga/gerencia apenas (a) apps cujos access-groups intersectam os grupos dele, e (b) membros desses mesmos grupos.
• Fatia 1 (camada de negócio, como o lead sugeriu): filtros nos handlers de Users/Groups/Apps por interseção de grupos quando role == Editor — sem migração, sem novo conceito de ownership.
• Fatia 2 (se necessário): papel "Editor de grupo" explícito por grupo.

Riscos a tratar

• Escalada: um Editor não pode conceder a si mesmo grupos que não tem, nem editar Admins.
• Apps abertos (sem access-groups) — quem os edita? (proposta: continuam Editor-globais, ou viram Admin-only ao delegar).

[milkway]

Plano de implementação

Decisões tomadas com o lead (2026-07-29):

1. O escopo alcança também as Aplicações, não só Usuários/Grupos.
2. Apps abertos (sem access-groups) continuam Editor-globais — app aberto não pertence a grupo nenhum, e tratá-lo como "de ninguém" o tornaria ineditável sem Admin.
3. Editor pode criar usuários, restritos aos grupos dele e nunca com papel Admin.

Modelo

O escopo de um Editor é o conjunto de grupos dele (users.groups). O primitivo de decisão já existe e está em produção há tempo: Spec::access_allows(is_admin, username, groups), usado hoje pelo proxy (routes/proxy.rs:447) e pela landing (routes/landing.rs:343). Esta issue estende o mesmo predicado ao painel, em vez de inventar ownership por app — que é exatamente o que o #517 rejeitou.

• Admin — sem escopo, tudo como hoje.
• Editor — vê e opera app cujo access-groups cruza com os grupos dele, ou que seja aberto; e gerencia pessoas dos mesmos grupos.
• Sessão por token (break-glass, actor: None, papel Admin) — sem escopo, inalterada.

Como o handler descobre o escopo

Hoje AdminSession carrega só {role, actor} — não carrega grupos. Duas saídas:

	custo	frescor
Guardar grupos na sessão	mexe no store em memória e no store Postgres de HA	fica velho quando a filiação muda (set_groups não revoga sessão)
Buscar a conta por request	um SELECT indexado por request de /admin/*	sempre fresco

Escolha: buscar por request. Já existe precedente exatamente com esse formato — o must_change_password_guard faz lookup por request em todo /admin/*, com o cache do #903 para copiar se aparecer pressão de latência. Frescor importa aqui: tirar alguém de um grupo tem que valer no próximo clique, não na próxima sessão.

Entra um extrator EditorScope que resolve {role, actor, groups} e expõe dois predicados — may_touch_spec(&Spec) e may_touch_user(&UserRow) — para os handlers não reimplementarem a interseção cada um do seu jeito.

Superfície real (medida)

Área	Handlers	Guarda hoje
specs.rs	8	RequireEditor
spec_form.rs	11	RequireEditor
dashboard.rs	5	RequireEditor
images.rs	6	RequireEditor
users.rs	14	RequireAdmin
groups.rs	6	RequireAdmin

Mais 24 pontos de can_access_section (Rust + templates) que decidem o que aparece na navegação.

Filtrar a listagem não é a proteção. Cada handler precisa da checagem no servidor, ou um Editor alcança um app/usuário fora do escopo adivinhando a URL. São ~30 handlers de app e ~20 de pessoas — o grosso do trabalho está aí, não na UI.

Invariantes de segurança (cada um vira teste)

1. Editor não concede grupo que ele não tem.
2. Editor não vê, não edita e não apaga um Admin.
3. Editor não define role = Admin (nem em criação, nem em edição).
4. Editor não se auto-promove nem se auto-adiciona a grupos.
5. Editor não alcança app/usuário fora do escopo por URL direta — checagem por handler, não só filtro de lista.
6. Grupos fora do escopo sobrevivem à edição. Se um usuário pertence aos grupos A (do editor) e B (não), o editor editando esse usuário não pode derrubar B silenciosamente. O set_groups hoje sobrescreve a lista inteira: o handler tem que reconstituir os grupos fora do escopo, ou renderizá-los como somente-leitura.

O invariante 6 é o mais fácil de errar e o mais chato de perceber depois.

Fatias

Fatia 0 — o primitivo, sem mudança de comportamento. Extrator EditorScope, os dois predicados, testes de unidade. Nada ligado ainda: mergeia sem alterar nenhuma tela.

Fatia 1 — Aplicações. Escopo em specs.rs + spec_form.rs + as réplicas do dashboard.rs (senão o Editor para/reinicia container de app fora do escopo). Criação: um app restrito precisa nascer com pelo menos um grupo do editor, senão ele cria algo que não consegue mais ver. images.rs fica de fora — mídia é biblioteca compartilhada, não tem dono.

Fatia 2 — Usuários. Abre a seção para Editor no can_access_section, com lista filtrada, guarda por handler, criação restrita (papel ∈ {Viewer, Editor}, grupos ⊆ os dele) e o invariante 6 na edição. Import CSV e reset de MFA ficam Admin-only.

Fatia 3 — Grupos. Abre a seção para Editor: lista só os grupos dele e gerencia filiação. Criar/renomear/apagar continua Admin-only — renomear e apagar reescrevem users.groups e access-groups de todos os specs, efeito muito além do escopo de quem chamou.

Fatia 4 — docs + verificação. Matriz de papéis no book/src/admin.md (que hoje afirma que Editor não alcança Usuários/Grupos), tabela de modelo de confiança no SECURITY.md, e smoke real com um Editor de verdade no navegador — não só teste de unidade.

Consequência de migração (tratar antes do deploy)

Hoje todo Editor opera o catálogo inteiro. Depois da fatia 1, um Editor sem grupos passa a ver apenas os apps abertos. Num upgrade isso é perda de acesso silenciosa.

Duas providências:

• Antes de deployar: conferir no box e no hugo quantas contas são Editor e que grupos têm. Se houver Editor sem grupo, ele precisa ganhar grupos antes da subida, ou vai abrir o painel sem os apps restritos.
• No código: warning de boot listando Editores sem grupo, no mesmo espírito do warning de fuso do Agendador de cronjobs avalia expressões cron em UTC — jobs disparam fora do horário local esperado #1042 — falha silenciosa tem que virar linha de log.

Ainda em aberto (não bloqueia começar pela fatia 0)

• Editor pode resetar senha de usuário do grupo dele? É a necessidade prática de helpdesk, mas num usuário compartilhado com outro time é movimento lateral. Tendo a permitir, dado que o usuário só é visível se estiver no grupo do editor.
• Editor pode apagar conta? Proponho não — apagar alcança grupos que ele não administra. O que ele faz é remover do grupo dele.
• Editor pode criar grupo novo? Proponho não (fatia 3 já reflete isso), mas é revisável se na prática o time precisar abrir um grupo sem passar pelo Admin.

[milkway]

Fechada: as cinco fatias estão na main e o gate combinado passou.

Fatia	Commit	PR
0 — primitivo EditorScope (sem mudar comportamento)	be02ffb	#1045
1 — Aplicações + réplicas do dashboard	adb29e9	#1046
2 — Usuários	c900f59	#1047
3 — Grupos (só filiação)	47f7c21	#1048
4 — rede de migração + docs	980473c	#1049

Rodei o gate na main depois de tudo mergeado, não só por fatia: as cinco tocaram os mesmos arquivos em sequência (scope.rs em três, auth.rs em duas, db/users.rs em três), e o que importava era confirmar que compõem. cargo test, clippy --all-targets -- -D warnings e i18n-check verdes.

O modelo que ficou

O escopo do Editor são os grupos dele, reusando a ideia do Spec::access_allows que já governa landing e proxy — não ownership por app, que o #517 rejeitou. Admin e a sessão break-glass seguem irrestritos. Alvo fora do escopo responde 404, não 403, para identificador chutado não revelar que o app de outro time existe. O escopo é lido a cada request, então remover alguém de um grupo vale no próximo clique.

Decisões suas, implementadas como acordado: escopo alcança Aplicações; apps abertos seguem Editor-globais; Editor cria usuário restrito aos grupos dele e nunca Admin.

Quatro achados de revisão que o gate não pegaria

Todos passavam verde nos três comandos — é o argumento prático para revisar o diff em vez de confiar no "gate verde" do agente.

1. Autorização sobre dado enriquecido (fatia 1). specs.rs::index monta linhas do SELECT enxuto e só depois preenche access_groups do catálogo efetivo; id ausente do mapa deixaria um app restrito parecendo aberto — e app aberto é Editor-global. Antecipado na revisão da fatia 0 e tratado nos dois caminhos da listagem.
2. Vazamento entre times via cache (fatia 1). A chave do snapshot do dashboard era só o locale. O agente achou o vazamento e o resolveu desligando o cache para escopados; rechaveei por (locale, escopo) para não jogar fora o ganho do perf(dashboard): share a single snapshot/broadcast across SSE subscribers #291, que é justamente o que evitou o travamento de abas do Admin trava ('carregando') com múltiplas abas abertas — esgotamento do pool HTTP/1.1 por ≥6 SSE seguradas (imune em HTTP/2) #1039/fix: replace process log SSE with incremental polling #1040.
3. Exclusão de Admin sensível a caixa (fatia 2). role <> 'admin' numa coluna TEXT sem CHECK, com o Épico: autenticação externa OIDC/SAML (Phase 8 / SSO) #934 (OIDC/LDAP) prestes a adicionar outro escritor de papéis. Virou lower(role), e verifiquei que o teste falha com o predicado antigo — teste que prende o buraco, não que o descreve.
4. Fallback de papel silencioso (fatia 3). Role::parse(...).unwrap_or(Role::Viewer) engolia a falha; uma conta que "de repente virou Viewer" é mistério indepurável pela interface. O fallback para menor privilégio ficou; a silêncio saiu.

Antes de subir no box e no hugo

Dar pelo menos um grupo a cada conta Editor na release atual, antes de iniciar a versão nova. Antes, Editor sem grupo operava o catálogo inteiro; agora alcança só apps abertos. O warning de boot nomeia as contas nessa situação, mas é rede de segurança, não substituto do passo.

Ficou de fora, deliberadamente

• Apagar conta, importar CSV e resetar MFA seguem Admin-only.
• Criar, renomear e apagar grupo seguem Admin-only: rewrite_group reescreve users.groups e o access-groups de todos os specs, efeito muito além do escopo de quem chama.
• Mídia (images.rs) não é escopada: biblioteca compartilhada, sem dono.
• App restrito só por access-users não tem fronteira de grupo e permanece Admin-only.

Se na prática o time precisar que um Editor abra grupo novo sem passar pelo Admin, é uma issue de follow-up — o modelo atual foi a escolha conservadora.