📦 mkplace-eks – Biblioteca de Middleware de Autenticação e Utilitários para Fastify 🚀

Bem-vindo ao mkplace-eks!
Esta biblioteca fornece middlewares, validações de ACL, manipulação de tokens JWT, exceções customizadas e utilitários úteis para aplicações Fastify rodando em ambientes Kubernetes (Amazon EKS). Tudo de forma padronizada e reutilizável. 🎉

📑 Sumário

• 🌟 Recursos Principais
• 🏗️ Arquitetura
• ⚙️ Instalação
• 🔧 Variáveis de Ambiente
• 📦 Exports
• 🧪 Mock de Escopos para Testes
• 🛠️ Uso Básico

🌟 Recursos Principais

✅ Autenticação de Tokens JWT

Middleware contextMiddleware que injeta os escopos e contextos na requisição via validação com o serviço k8s-authorizer.

🔐 Validação de ACL

Função validateAcl() para verificar se o token possui os escopos e contextos necessários para executar determinada operação.

🧪 Modo Mock para Testes e CI

Com MOCK_SCOPES=true, a validação de permissões e contextos será simulada com base no que for solicitado, sem exigir token real.

⚠️ Exceções Personalizadas

Classes de erro padronizadas (UnauthorizedError, ForbiddenError, FatalError, etc.) com statusCode, errorCode e exceptionType para integração fácil com handlers globais.

🛠️ Utilitários Adicionais

• Enum HttpStatusCodes
• Função mkCustomId() para gerar IDs únicos

🏗️ Arquitetura

O mkplace-eks abstrai a camada de autenticação e autorização da aplicação, centralizando a lógica em uma lib que:

• Se comunica com um serviço interno (k8s-authorizer) para validar tokens.
• Injeta os escopos/contextos no objeto de request do Fastify.
• Permite validação granular de permissões por rota usando validateAcl().
• Usa classes de exceção unificadas para manter os erros rastreáveis e consistentes em toda a stack.

⚙️ Instalação

yarn add @mkplace/eks

Ou com npm:

npm install @mkplace/eks

Para compilar o TypeScript localmente (caso esteja desenvolvendo a lib):

yarn build

🔧 Variáveis de Ambiente

| Variável | Obrigatório | Descrição | | ------------- | ----------- | ------------------------------------------------------ | | MOCK_SCOPES | Não | Se true, ativa o modo de escopos/contextos simulados |

💡 No ambiente de testes locais ou CI/CD, use MOCK_SCOPES=true.

📦 Exports

A lib exporta os seguintes recursos:

✅ Exceptions

FatalError;
ForbiddenError;
GenericException;
IntegrationError;
NotFoundError;
PreconditionFailedError;
UnauthorizedError;
ValidationError;

✅ Utilitários

HttpStatusCodes;
mkCustomId();

✅ Auth & Middleware

contextMiddleware; // Middleware para popular o requestContext
validateAcl(); // Função para validar escopos/contextos
ExtendedFastifyRequest; // Tipagem extendida da request com contexto e metadados

🧪 Mock de Escopos para Testes

Ao definir MOCK_SCOPES=true, a função validateAcl() não faz nenhuma validação real e apenas retorna os contextos solicitados no formato:

{
  accountId: "mock-accountId",
  storeId: "mock-storeId"
}

Ideal para testes locais e pipelines (GitHub Actions, etc).

🛠️ Uso Básico

🧩 1. Use o middleware no Fastify

app.addHook("preHandler", contextMiddleware);

🔐 2. Proteja suas rotas com validateAcl

app.get("/secure-endpoint", async (request, reply) => {
  const { accountId } = await validateAcl(
    request.requestContext.authorizer,
    ["admin:read", "user:manage"], // permissões obrigatórias
    ["accountId"], // contextos obrigatórios
    ["storeId"] // contextos opcionais
  );

  return { message: `Access granted for account ${accountId}` };
});

🆕 Modo de Acesso via APP_KEY (Bypass de Autorização)

Além do comportamento já existente com MOCK_SCOPES, a biblioteca agora permite realizar chamadas sem header Authorization, desde que alguns critérios sejam atendidos. Esse mecanismo é útil para testes locais, comunicação interna entre serviços no Kubernetes e cenários onde um bypass controlado é necessário.

🔑 Como funciona o Bypass com APP_KEY

Quando a requisição não possui Authorization, o middleware aceita a autenticação desde que:

1. O host da requisição seja:
   • localhost, ou
   • um host interno Kubernetes (*.svc.cluster.local)
2. O protocolo da requisição seja http
3. O header x-app-key corresponda exatamente à variável de ambiente APP_KEY

🔧 Escopos e Contextos Simulados

Quando esses critérios são atendidos, os escopos e contextos podem ser enviados diretamente via headers:

| Header | Formato | Exemplo | | ------------ | ------------------------------------------------------ | ----------------------------------- | | x-scopes | Lista separada por & comercial | admin/read/action&admin/read/test | | x-contexts | Lista no formato key=value separados por & comercial | accountId=123&storeId=89 |

O middleware converte automaticamente esses valores e os injeta em:

request.requestContext.authorizer;

Da mesma forma que ocorreria com a validação real do Authorization.

📌 Exemplo de Uso

GET /secure-endpoint
Host: my-service.namespace.svc.cluster.local
x-app-key: my-secret-key
x-scopes: admin/read/action&admin/read/test
x-contexts: accountId=abc123&storeId=xyz987

Esse mecanismo permite que serviços internos ou testes executem chamadas autenticadas sem necessidade de um JWT válido.

⚠️ Importante

Esse modo deve ser usado em ambientes controlados. Ele depende explicitamente de:

• Hostnames restritos
• Protocolo HTTP interno
• Conhecimento da APP_KEY

Não substitui mecanismos de autenticação formais em ambientes públicos.

📬 Contribuições

Pull Requests são bem-vindos! Se for algo sensível à segurança (como manipulação de token), priorize abrir uma Issue para discutirmos antes.

📄 Licença

MIT – © mkplace