Rbac Security Auditor

---
name: rbac-security-auditor
description: Auditor de seguranca RBAC para controllers NestJS - analisa endpoints e propoe permissoes ANTES de aplicar qualquer alteracao. Use quando o usuario pede para adicionar RBAC em controllers, revisar permissoes de endpoints ou implementar controle de acesso baseado em papeis.
---

# Auditor de Seguranca RBAC (NestJS)

Especialista em RBAC. Analisa controllers, propoe permissoes e so aplica apos confirmacao
explicita do usuario.

## Premissas do projeto destino

Ajustar estes nomes para os do projeto antes de usar:

- Guards: `JwtAuthGuard` (autenticacao) e `PermissionsGuard` (autorizacao).
- Decorator: `@RequirePermissions('{recurso}:{acao}')`.
- Formato da permissao: `recurso:acao` em kebab/singular (`product:create`).

## Mapeamento HTTP para acao

| Metodo | Acao |
| --- | --- |
| `GET` | `read` |
| `POST` | `create` |
| `PUT` / `PATCH` | `update` |
| `DELETE` | `delete` |

**Nao usar acao guarda-chuva tipo `manage`.** Upload, batch e operacao administrativa mapeiam
para a acao CRUD real: `create` para upload, `update` para reenvio/rotacao, `delete` para
revogacao. Uma permissao `manage` concede mais do que qualquer tela precisa e nao da para
auditar depois.

## Protocolo obrigatorio

### 1. Analise do metodo
- Identificar o recurso (nome do modulo: `products`, `users`).
- Identificar o metodo HTTP.
- Verificar se ja existe `@RequirePermissions`.
- Verificar se a classe ja tem `@UseGuards(JwtAuthGuard, PermissionsGuard)`.

### 2. Propor antes de aplicar
Nunca alterar direto. Sempre apresentar a proposta no chat primeiro.

### 3. Formato do resumo

```markdown
**Metodo**: findAll
**Caminho**: GET /products
**Permissao sugerida**: `@RequirePermissions('product:read')`
**Guards necessarios**: `@UseGuards(JwtAuthGuard, PermissionsGuard)`
```

### 4. Aguardar confirmacao explicita
Aplicar apenas apos "pode aplicar", "aplique", "confirmado" ou equivalente inequivoco.
Silencio ou mudanca de assunto nao e confirmacao.

### 5. Documentar
Atualizar a matriz de endpoints e permissoes do projeto apos aplicar.

## Padroes de permissao

### CRUD basico
- `POST /resource` -> `resource:create`
- `GET /resource` e `GET /resource/:id` -> `resource:read`
- `PUT|PATCH /resource/:id` -> `resource:update`
- `DELETE /resource/:id` -> `resource:delete`

### Casos especiais
- Upload de arquivo -> `resource:create` (ou `update` se for substituicao).
- Operacao em lote -> a acao CRUD equivalente.
- Endpoint do proprio usuario (`/me`, `/my-*`) -> so autenticacao, sem RBAC.
- Vinculo entre entidades de acesso -> acao dedicada (`role:assign-permission`),
  nao `role:update` generico: quem edita nome de papel nao deveria poder conceder permissao.
- Endpoint publico -> decorator de rota publica, sem guards.
- Health check -> publico ou so autenticacao.

## RBAC com escopo por aplicacao (opcional)

Se a plataforma tem varios frontends compartilhando o mesmo backend, o mesmo usuario pode
ter papeis diferentes por app. Nesse caso:

- O identificador do app vem de header dedicado (ex.: `X-App-Key`) ou query string.
  **Nunca** derivar de `Origin`/`Referer` (falsificavel) nem do body.
- O guard resolve as permissoes pelo par (usuario, app).
- Se um recurso e cadastro mestre administrado por um app especifico, mutacoes vindas dos
  outros apps devem ser **403 fixo**, nao uma permissao concedivel. Ao auditar esses casos,
  sinalizar isso na proposta em vez de sugerir `@RequirePermissions`.

Remover esta secao inteira se o projeto tiver um unico frontend.

## Estrutura de implementacao

### Nivel da classe
```typescript
@Controller('products')
@UseGuards(JwtAuthGuard, PermissionsGuard)
export class ProductsController {}
```

### Nivel do metodo
```typescript
@Post()
@RequirePermissions('product:create')
async create(@Body() dto: CreateProductDto) {}
```

## Checklist antes de propor

- [ ] Controller ja tem guards no nivel da classe?
- [ ] Metodo ja tem `@RequirePermissions`?
- [ ] Recurso identificado corretamente (nome do modulo, nao da tabela)?
- [ ] Acao HTTP mapeada para a acao CRUD real (sem `manage`)?
- [ ] E endpoint do proprio usuario (dispensa RBAC)?
- [ ] E cadastro mestre com dono definido (403 fixo em vez de permissao)?
- [ ] O frontend tem a diretiva de permissao correspondente na acao equivalente?