Modelo de Permissões

O middag-account implementa um sistema de permissões multi-tenant baseado em associação a organização, hierarquia de cargos e permissões com escopo. Todo acesso a dados é delimitado pelo header X-Middag-Organization.

Limite Organizacional

Todas as queries filtram por organization_id. Dados de uma organização nunca vazam para outra. O limite é aplicado em múltiplas camadas:

1. OrganizationMiddleware -- Válida o header X-Middag-Organization em toda requisição com escopo de organização
2. PermissionsMiddleware -- Verifica que o usuário é um colaborador da organização alvo
3. Camada de repositório -- Todo método de query exige organization_id como parâmetro

Requisição HTTP
  -> AuthMiddleware (validar JWT, definir WP_User)
  -> PermissionsMiddleware (verificar cargo + escopos)
  -> OrganizationMiddleware (validar associação à org)
  -> Controller (executar com contexto de org)

Header X-Middag-Organization

Obrigatório em todos os endpoints que operam com dados de escopo organizacional. O valor é o ID inteiro da organização.

GET /wp-json/middag-account/v1/entitlements
Authorization: Bearer eyJ...
X-Middag-Organization: 42

Etapas de válidação:

1. Header presente -- senão 400 Bad Request
2. Organização existe -- senão 404 Not Found
3. Usuário é colaborador da organização -- senão 403 Forbidden
4. Contexto da organização é definido na requisição para uso downstream

Hierarquia de Cargos

Os cargos determinam o nível de acesso base dentro de uma organização. Definidos no enum RoleHierarchy:

Cargo	Peso	Gerenciar Membros	Alterar Org	Excluir Org
owner	100	Sim (todos)	Sim	Sim
admin	80	Sim (member/guest)	Sim (com escopo)	Não
member	50	Não	Não	Não
guest	20	Não	Não	Não
pending	0	Não	Não	Não

Um cargo supera outro se seu peso for maior. O método outranks() compara dois cargos:

RoleHierarchy::Owner->outranks(RoleHierarchy::Admin); // true
RoleHierarchy::Member->outranks(RoleHierarchy::Admin); // false

Escopos de Permissão

Permissões granulares são controladas por escopos atribuídos a cada colaborador. Definidos no enum PermissionScope:

Escopo	Controla Acesso A
organization	Configurações e perfil da organização
finances	Faturas, notas fiscais, cobranças
orders	Pedidos WooCommerce, reembolsos
licenses	Gerenciamento de licenças de software
tickets	Tickets de suporte, solicitações de serviço
quotes	Visualização de quotes, aceitar/rejeitar
contracts	Visualização de contratos, download de PDF
documents	Documentos da organização
downloads	Downloads de produtos

Cada escopo mapeia para um campo booleano na CollaboratorEntity:

$collaborator->canManageFinances;  // true/false
$collaborator->canManageOrders;    // true/false

O cargo owner tem acesso implícito a todos os escopos. Os cargos admin e member exigem atribuição explícita de escopo.

Proteção de Rotas

Toda rota REST declara seu cargo e escopos obrigatórios. O PermissionsMiddleware aplica essas regras no momento da requisição:

Rota: GET /invoices
Escopo obrigatório: finances
Cargo obrigatório: member (mínimo)

Verificação:
1. Carregar colaborador para (user_id, organization_id)
2. Verificar cargo >= member (peso >= 50)
3. Verificar que o colaborador possui escopo "finances"
4. Se escopo ausente -> 403 "Scope not authorized: finances"

Capabilities Customizadas do WordPress

O plugin registra capabilities customizadas via filtro user_has_cap. Elas mapeiam o cargo e os escopos do colaborador dentro do contexto organizacional, fazendo a ponte entre o modelo de permissões do middag e o sistema nativo de capabilities do WordPress.

Escopos JWT

O payload do JWT inclui os escopos do usuário para a organização padrão:

{
    "sub": 42,
    "org": 15,
    "roles": [
        "admin"
    ],
    "scopes": [
        "organization",
        "finances",
        "orders",
        "licenses"
    ]
}

O array scopes no JWT representa as permissões do colaborador. Um wildcard "*" concede acesso a todos os escopos.

Header X-Middag-Company

O header opcional X-Middag-Company (middag_br ou middag_global) direciona requisições para a entidade legal correta em operações de entidade dual (contas Stripe, sistemas fiscais). Não afeta verificações de permissão.

Relacionados

• Visão Geral da REST API -- Pipeline de middleware
• Pontos de Extensão -- Hooks para lógica de permissão customizada
• Labels de Status -- Cargos de colaborador