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
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. 🎉
---
- 🌟 Recursos Principais
- 🏗️ Arquitetura
- ⚙️ Instalação
- 🔧 Variáveis de Ambiente
- 📦 Exports
- 🧪 Mock de Escopos para Testes
- 🛠️ Uso Básico
---
Middleware contextMiddleware que injeta os escopos e contextos na requisição via validação com o serviço k8s-authorizer.
Função validateAcl() para verificar se o token possui os escopos e contextos necessários para executar determinada operação.
Com MOCK_SCOPES=true, a validação de permissões e contextos será simulada com base no que for solicitado, sem exigir token real.
Classes de erro padronizadas (UnauthorizedError, ForbiddenError, FatalError, etc.) com statusCode, errorCode e exceptionType para integração fácil com handlers globais.
- Enum HttpStatusCodes
- Função mkCustomId() para gerar IDs únicos
---
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.
---
``bash`
yarn add @mkplace/eks
Ou com npm:
`bash`
npm install @mkplace/eks
Para compilar o TypeScript localmente (caso esteja desenvolvendo a lib):
`bash`
yarn build
---
| 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.
---
A lib exporta os seguintes recursos:
`ts`
FatalError;
ForbiddenError;
GenericException;
IntegrationError;
NotFoundError;
PreconditionFailedError;
UnauthorizedError;
ValidationError;
`ts`
HttpStatusCodes;
mkCustomId();
`ts`
contextMiddleware; // Middleware para popular o requestContext
validateAcl(); // Função para validar escopos/contextos
ExtendedFastifyRequest; // Tipagem extendida da request com contexto e metadados
---
Ao definir MOCK_SCOPES=true, a função validateAcl() não faz nenhuma validação real e apenas retorna os contextos solicitados no formato:
`ts`
{
accountId: "mock-accountId",
storeId: "mock-storeId"
}
Ideal para testes locais e pipelines (GitHub Actions, etc).
---
`ts`
app.addHook("preHandler", contextMiddleware);
`ts
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} };`
});
---
(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.
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*.svc.cluster.local
- um host interno Kubernetes ()http
2. O protocolo da requisição seja
3. O header corresponda exatamente à variável de ambiente APP_KEY
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:
`ts`
request.requestContext.authorizer;
Da mesma forma que ocorreria com a validação real do Authorization.
`http`
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.
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.
---
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.
---
MIT – © mkplace
`
``