npm package: @mkplace/eks
Description: 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 
Latest version: 3.2.0

# 📦 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](#-recursos-principais)
- [🏗️ Arquitetura](#️-arquitetura)
- [⚙️ Instalação](#️-instalação)
- [🔧 Variáveis de Ambiente](#-variáveis-de-ambiente)
- [📦 Exports](#-exports)
- [🧪 Mock de Escopos para Testes](#-mock-de-escopos-para-testes)
- [🛠️ Uso Básico](#️-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

```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á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

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

### ✅ Utilitários

```ts
HttpStatusCodes;
mkCustomId();
```

### ✅ Auth & Middleware

```ts
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:

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

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

---

## 🛠️ Uso Básico

### 🧩 1. Use o middleware no Fastify

```ts
app.addHook("preHandler", contextMiddleware);
```

### 🔐 2. Proteja suas rotas com `validateAcl`

```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}` };
});
```

---

## 🆕 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:

```ts
request.requestContext.authorizer;
```

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

### 📌 Exemplo de Uso

```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.

### ⚠️ 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

```

```