# Auth/RBAC por App Membership em `/api/v1/data`

Atualizado em: 2026-02-27

## Objetivo
Garantir isolamento de acesso por `app` e por papel do usuario em todas as rotas `GET/POST/PATCH/DELETE` de `/api/v1/data/*`, com suporte a restricao por propriedade (`constraint_property`) quando configurada.

## Status Atual

### Implementado
- Enforce global no BFF Nuxt para toda rota `/api/v1/data/*`.
- Decisao de acesso central no Laravel via `GET /api/v1/auth/app-access/{appName}`.
- Aplicacao de constraint por dado nos handlers de:
  - listagem;
  - lookup;
  - dashboard metrics;
  - leitura por id;
  - update por id;
  - delete por id;
  - create.
- Suporte a aliases de app (`-` e `_`) na validacao.
- Suporte a membership curinga `app='*'` no endpoint `app-access` (acesso global por membership).
- Usuarios privilegiados com membership `owner` em todos os apps conhecidos e tambem em `task-board`/`task_board`.

### Ajuste de abilities
- Como o schema atual de `users` neste ambiente nao possui colunas `role` e `custom_abilities`, o calculo de abilities globais foi adaptado:
  - se houver membership ativo `app='*'` com role `owner/admin`, `allAbilities()` retorna `['*']`.
- Resultado esperado apos novo login: `abilities` no auth devem incluir `*`.

## Plano Tecnico por Camadas

### 1) Frontend
- Continuar enviando `auth_token` (cookie) e/ou `Authorization: Bearer`.
- Enviar contexto de `app` quando necessario (`?app=` ou `x-fastapp-app`) em casos ambiguos.
- Exibir UX consistente:
  - `401` para sessao/token invalido;
  - `403` para bloqueio de escopo/permissao.

### 2) Backend (Nuxt BFF)
- Middleware `server/middleware/rbac-data-scope.ts`:
  - intercepta `/api/v1/data/*`;
  - resolve `object` e `action` (`read/create/update/delete/lookup/metrics`);
  - resolve `app` por query/header/referer + metadata do objeto;
  - valida no Laravel (`/api/v1/auth/app-access/{app}`), com fallback em `/api/v1/auth/me` para compatibilidade;
  - injeta escopo em `event.context.rbacDataScope`.
- Utilitario `server/utils/rbac-data-scope.ts`:
  - injeta constraint no `where`;
  - injeta/valida constraint no body de escrita;
  - valida registro por `id` dentro do escopo;
  - injeta constraint na query forward para fontes externas.

### 3) Backend (Laravel API)
- Endpoint `GET /api/v1/auth/app-access/{appName}`:
  - valida membership no app solicitado;
  - considera aliases e membership curinga `*`;
  - resolve permissao por role + acao + objeto;
  - aplica fallback conservador para leitura quando nao ha matriz de permissao;
  - retorna `constraint` quando existir `constraint_property`.

### 4) Schema
- `fastapp_permission` deve manter convencao de nomes de permissao:
  - `objeto-read|create|update|delete`, `data.read`, `data:create`, etc.
- Para escopo por dono/equipe, preencher `constraint_property` (ex.: `owner_id`, `team_id`).

### 5) Dados
- `fastapp_user_app` e a fonte principal de autorizacao por app.
- Para acesso total administrado por membership, manter:
  - memberships por app com role `owner`; ou
  - membership curinga `app='*'` com role `owner`.
- Garantir `reference_id`/`reference_object` quando `constraint_property` exigir.

## Criterios de Aceite
1. Sem token, qualquer rota `/api/v1/data/*` retorna `401`.
2. Sem membership valido no app (nem curinga `*`), retorna `403`.
3. Com membership `owner/admin`, operacoes `POST/PATCH/DELETE` sao permitidas.
4. Com membership de leitura apenas, escrita retorna `403`.
5. Com `constraint_property`, leitura e escrita respeitam o escopo por registro.
6. Com membership curinga `*` role `owner`, acesso deve funcionar em app novo sem cadastro manual previo.
7. `GET /api/v1/auth/me` e login devem refletir `abilities: ['*']` para usuario com membership curinga `*` owner/admin (apos novo login/token).

## Validacao de Regressao
1. Smoke por rota:
   - `GET /api/v1/data/:object`
   - `POST /api/v1/data/:object`
   - `GET /api/v1/data/:object/:id`
   - `PATCH /api/v1/data/:object/:id`
   - `DELETE /api/v1/data/:object/:id`
   - `GET /api/v1/data/:object/lookup`
   - `GET /api/v1/data/:object/dashboard-metrics`
2. Matriz de papeis por app:
   - `owner/admin/member/viewer` x `read/create/update/delete`.
3. Casos de app ambiguo:
   - mesmo `object` em apps diferentes com `?app=` distinto.
4. Casos de aliases:
   - `task-board` vs `task_board`;
   - `central-filtros` vs `central_filtros`.
5. Caso curinga:
   - usuario com app `*` consegue acessar app nao previamente cadastrado no membership nominal.
6. Fontes externas:
   - confirmar forward de constraint e bloqueio por membership.
7. Nao regressao funcional:
   - envelope legado `{ total, limit, skip, data }` preservado.

## Observacoes
- O projeto legado `api-fastapp-cloud` nao entra no fluxo ativo.
- Base ativa considerada: `laravel-api`.
- O typecheck global do `lead-nuxt` possui erros preexistentes fora deste escopo; validar regressao focando nas rotas RBAC e no fluxo de auth.