@adatechnology/auth-keycloak 0.0.7 → 0.0.8

package/README.md

@@ -5,34 +5,35 @@ Módulo Keycloak para autenticação de clients e usuários, seguindo o padrão
 Este pacote fornece um cliente leve para interagir com o Keycloak (obter/refresh de tokens, introspecção, userinfo)
 e um interceptor opcional. O módulo foi projetado para ser usado junto ao `@adatechnology/http-client`.
 
-Principais exportações
+### Principais exportações
 
-- `KeycloakModule` — módulo principal. Suporta `KeycloakModule.forRoot(config?)` (padrão dinâmico).
-- `KEYCLOAK_CLIENT` — provider token para injetar o cliente Keycloak (use `@Inject(KEYCLOAK_CLIENT)`).
-- `KEYCLOAK_HTTP_INTERCEPTOR` — provider token para injetar o interceptor (se necessário).
+- `KeycloakModule` — módulo principal. Suporta `KeycloakModule.forRoot(config?)`.
+- `KEYCLOAK_CLIENT` — provider token para injetar o cliente Keycloak (`@Inject(KEYCLOAK_CLIENT)`).
+- `KEYCLOAK_HTTP_INTERCEPTOR` — provider token para injetar o interceptor (opcional).
+- `Roles` / `RolesGuard` — decorator e guard para autorização baseada em roles.
+- `KeycloakError` — classe de erro tipada com `statusCode` e `details`.
 
-Instalação
+### Instalação
 
-Este pacote já declara dependência interna de workspace para `@adatechnology/http-client`. Em um monorepo PNPM/Turbo o pacote é resolvido automaticamente.
-
-Uso
+```bash
+# Este pacote já declara dependências de workspace para http-client, logger e cache.
+# Em um monorepo PNPM/Turbo os pacotes são resolvidos automaticamente.
+```
 
-- Configuração via código (recomendado quando quiser injetar configuração manualmente):
+### Uso básico
 
 ```ts
 import { Module } from "@nestjs/common";
-import { HttpModule } from "@adatechnology/http-client";
 import { KeycloakModule } from "@adatechnology/auth-keycloak";
 
 @Module({
   imports: [
-    HttpModule.forRoot({ baseURL: "https://pokeapi.co/api/v2", timeout: 5000 }),
     KeycloakModule.forRoot({
       baseUrl: "https://keycloak.example.com",
-      realm: "BACKEND",
+      realm: "myrealm",
       credentials: {
-        clientId: "backend-api",
-        clientSecret: "backend-api-secret",
+        clientId: "my-client",
+        clientSecret: "my-secret",
         grantType: "client_credentials",
       },
     }),
@@ -41,68 +42,125 @@ import { KeycloakModule } from "@adatechnology/auth-keycloak";
 export class AppModule {}
 ```
 
-- Configuração via `ConfigService` / variáveis de ambiente (padrão quando não passar `forRoot`):
+### Injeção do cliente
 
-As variáveis usadas pelo módulo interno são:
+```ts
+import { Inject } from '@nestjs/common';
+import { KEYCLOAK_CLIENT } from '@adatechnology/auth-keycloak';
+import type { KeycloakClientInterface } from '@adatechnology/auth-keycloak';
 
-- `KEYCLOAK_BASE_URL` (padrão: `http://localhost:8081`)
-- `KEYCLOAK_REALM` (padrão: `BACKEND`)
-- `KEYCLOAK_CLIENT_ID` (padrão: `backend-api`)
-- `KEYCLOAK_CLIENT_SECRET` (padrão: `backend-api-secret`)
+constructor(
+  @Inject(KEYCLOAK_CLIENT) private readonly keycloakClient: KeycloakClientInterface,
+) {}
+```
+
+### API do cliente
 
-API rápida (via token)
+| Método | Descrição |
+|---|---|
+| `getAccessToken()` | Obtém token com cache automático e deduplicação de requisições |
+| `getTokenWithCredentials({ username, password })` | Login com credenciais (resource-owner password grant) |
+| `refreshToken(refreshToken)` | Renova token e atualiza o cache interno |
+| `validateToken(token)` | Introspecção via endpoint `/token/introspect` |
+| `getUserInfo(token)` | Retorna claims via endpoint `/userinfo` |
+| `clearTokenCache()` | Remove o token do cache (útil para forçar renovação) |
 
-- `KEYCLOAK_CLIENT.getAccessToken()` — obtém token com cache e deduplicação de requisições.
-- `KEYCLOAK_CLIENT.refreshToken(refreshToken)` — renova token.
-- `KEYCLOAK_CLIENT.validateToken(token)` — introspecção no Keycloak.
-- `KEYCLOAK_CLIENT.getUserInfo(token)` — retorna userinfo.
+### Cache de token
 
-Exemplo de injeção no NestJS:
+O `KeycloakClient` usa `@adatechnology/cache` para armazenar o access token obtido via `client_credentials`.
+Por padrão é criado um `InMemoryCacheProvider` local. Você pode substituir por Redis ou qualquer implementação
+de `CacheProviderInterface` injetando o provider `CACHE_PROVIDER` no contexto do módulo:
 
 ```ts
-import { Inject } from '@nestjs/common';
-import { KEYCLOAK_CLIENT } from '@adatechnology/auth-keycloak';
-import type { KeycloakClientInterface } from '@adatechnology/auth-keycloak';
+import { Module } from "@nestjs/common";
+import { CacheModule } from "@adatechnology/cache";
+import { KeycloakModule } from "@adatechnology/auth-keycloak";
+
+@Module({
+  imports: [
+    // Registra CACHE_PROVIDER como Redis — KeycloakClient o usará automaticamente
+    CacheModule.forRoot({
+      type: 'redis',
+      redis: { host: 'localhost', port: 6379 },
+    }),
+    KeycloakModule.forRoot({ ... }),
+  ],
+})
+export class AppModule {}
+```
 
-constructor(@Inject(KEYCLOAK_CLIENT) private readonly keycloakClient: KeycloakClientInterface) {}
+Se `CACHE_PROVIDER` não for registrado no módulo, o `KeycloakClient` cria um `InMemoryCacheProvider`
+interno sem necessidade de configuração adicional.
+
+O TTL do cache é derivado do campo `expires_in` do token (com 60 segundos de margem). Você pode
+sobrescrever com a opção `tokenCacheTtl` (em **milissegundos**):
+
+```ts
+KeycloakModule.forRoot({
+  ...
+  tokenCacheTtl: 60_000, // força TTL de 60 s independente do token
+})
 ```
 
-Notas
+### Propagação de contexto de log (cascade)
 
-- Este módulo depende de `@adatechnology/http-client` (provider `HTTP_PROVIDER`) para realizar chamadas HTTP ao Keycloak. Configure o `HttpModule` conforme necessário na aplicação que consome este pacote.
-- O interceptor `KeycloakHttpInterceptor` é fornecido caso queira integrar com outras camadas que aceitem interceptors.
+O cliente lê o `logContext` do `AsyncLocalStorage` da lib `@adatechnology/logger`. Para que os logs
+de downstream (keycloak → cache) mostrem `className.methodName` da origem correta, use `runWithContext`
+no controller:
 
-## Autorização (decorator @Roles)
+```ts
+import { getContext, runWithContext } from '@adatechnology/logger';
 
-O pacote agora fornece um decorator `@Roles()` e um `RolesGuard` para uso nas rotas do NestJS. Exemplos:
+// No controller
+private withCtx<T>(logContext: object, fn: () => Promise<T>): Promise<T> {
+  return runWithContext({ ...(getContext() ?? {}), logContext }, fn);
+}
+
+async getToken() {
+  const logContext = { className: 'MyController', methodName: 'getToken' };
+  return this.withCtx(logContext, () => this.keycloakService.getAccessToken());
+}
+```
+
+Resultado no log:
+```
+[MyController.getToken][KeycloakClient.getAccessToken] → cache miss → request token
+[MyController.getToken][InMemoryCacheProvider.set] → token cached
+```
+
+### Autorização com @Roles
 
 ```ts
 import { Controller, Get, UseGuards } from "@nestjs/common";
-import { Roles } from "@adatechnology/auth-keycloak";
-import { RolesGuard } from "@adatechnology/auth-keycloak";
+import { Roles, RolesGuard } from "@adatechnology/auth-keycloak";
 
 @Controller("secure")
-@UseGuards(RolesGuard)
 export class SecureController {
+  @Get("public")
+  @UseGuards(RolesGuard)
+  public() {
+    return { ok: true };
+  }
+
   @Get("admin")
-  @Roles("admin") // aceita um ou mais roles (OR por padrão)
+  @UseGuards(RolesGuard)
+  @Roles("admin")
   adminOnly() {
     return { ok: true };
   }
 
   @Get("team")
-  @Roles({ roles: ["manager", "lead"], mode: "all" }) // requer ambos (AND)
+  @UseGuards(RolesGuard)
+  @Roles({ roles: ["manager", "lead"], mode: "all" }) // AND — requer ambas as roles
   teamOnly() {
     return { ok: true };
   }
 }
 ```
 
-O `RolesGuard` extrai roles do payload do JWT (claims `realm_access.roles` e `resource_access[clientId].roles`). Por padrão o decorator verifica ambos (realm e client). Você pode ajustar o comportamento usando as opções `{ type: 'realm'|'client'|'both' }`.
+O `RolesGuard` extrai roles de `realm_access.roles` e `resource_access[clientId].roles` do JWT.
 
-## Erros
-
-O pacote exporta `KeycloakError` (classe) que é usada para representar falhas nas chamadas HTTP ao Keycloak. A classe contém `statusCode` e `details` para permitir um tratamento declarativo dos erros na aplicação que consome a biblioteca. Exemplo:
+### Tratamento de erros
 
 ```ts
 import { KeycloakError } from "@adatechnology/auth-keycloak";
@@ -111,17 +169,31 @@ try {
   await keycloakClient.getUserInfo(token);
 } catch (e) {
   if (e instanceof KeycloakError) {
-    // tratar problema específico de Keycloak
-    console.error(e.statusCode, e.details);
+    console.error(e.statusCode, e.details, e.keycloakError);
   }
   throw e;
 }
 ```
 
-Contribuições
+### Variáveis de ambiente (referência)
+
+| Variável | Padrão |
+|---|---|
+| `KEYCLOAK_BASE_URL` | `http://localhost:8081` |
+| `KEYCLOAK_REALM` | `BACKEND` |
+| `KEYCLOAK_CLIENT_ID` | `backend-api` |
+| `KEYCLOAK_CLIENT_SECRET` | `backend-api-secret` |
+
+### Notas
+
+- Este módulo depende de `@adatechnology/http-client` para chamadas HTTP ao Keycloak.
+- O interceptor `KeycloakHttpInterceptor` pode ser registrado como `APP_INTERCEPTOR` para integração global.
+- `clearTokenCache()` é assíncrono desde a versão `0.0.7` (retorna `Promise<void>`).
+
+### Contribuições
 
 Relate issues/PRs no repositório principal. Mantenha compatibilidade com o padrão usado pelo `HttpModule`.
 
-Licença
+### Licença
 
 MIT

package/dist/index.d.ts

@@ -75,7 +75,7 @@ interface KeycloakClientInterface {
     /**
      * Clear the internal access token cache maintained by the client.
      */
-    clearTokenCache(): void;
+    clearTokenCache(): Promise<void>;
 }
 /**
  * Provider-facing interface type to be used when injecting the keycloak provider token.

package/dist/index.js

@@ -284,11 +284,14 @@ var import_common5 = require("@nestjs/common");
 var import_core2 = require("@nestjs/core");
 var import_http_client2 = require("@adatechnology/http-client");
 var import_logger2 = require("@adatechnology/logger");
+var import_cache3 = require("@adatechnology/cache");
 
 // src/keycloak.client.ts
 var import_common = require("@nestjs/common");
 var import_http_client = require("@adatechnology/http-client");
 var import_logger = require("@adatechnology/logger");
+var import_cache = require("@adatechnology/cache");
+var import_cache2 = require("@adatechnology/cache");
 
 // src/errors/keycloak-error.ts
 var KeycloakError = class _KeycloakError extends Error {
@@ -307,7 +310,8 @@ var KeycloakError = class _KeycloakError extends Error {
 
 // src/keycloak.client.ts
 var LIB_NAME = "@adatechnology/auth-keycloak";
-var LIB_VERSION = "0.0.2";
+var LIB_VERSION = "0.0.7";
+var TOKEN_CACHE_KEY = "keycloak:access_token";
 function extractErrorInfo(err) {
   var _a, _b, _c, _d, _e;
   const statusCode = (err == null ? void 0 : err.status) ?? ((_a = err == null ? void 0 : err.response) == null ? void 0 : _a.status);
@@ -333,18 +337,21 @@ function extractErrorInfo(err) {
   };
 }
 var KeycloakClient = class {
-  constructor(config, httpProvider, logger) {
+  constructor(config, httpProvider, logger, cacheProvider) {
     this.config = config;
     this.httpProvider = httpProvider;
     this.logger = logger;
+    this.cacheProvider = cacheProvider ?? new import_cache.InMemoryCacheProvider(logger);
   }
-  tokenCache = null;
+  cacheProvider;
   tokenPromise = null;
   log(level, message, libMethod, meta) {
     if (!this.logger) return;
+    const loggerCtx = (0, import_logger.getContext)();
     const httpCtx = (0, import_http_client.getHttpRequestContext)();
-    const requestId = httpCtx == null ? void 0 : httpCtx.requestId;
-    const source = (httpCtx == null ? void 0 : httpCtx.className) && (httpCtx == null ? void 0 : httpCtx.methodName) ? `${httpCtx.className}.${httpCtx.methodName}` : void 0;
+    const logContext = loggerCtx == null ? void 0 : loggerCtx.logContext;
+    const requestId = (loggerCtx == null ? void 0 : loggerCtx.requestId) ?? (httpCtx == null ? void 0 : httpCtx.requestId);
+    const source = (logContext == null ? void 0 : logContext.className) && (logContext == null ? void 0 : logContext.methodName) ? `${logContext.className}.${logContext.methodName}` : (httpCtx == null ? void 0 : httpCtx.className) && (httpCtx == null ? void 0 : httpCtx.methodName) ? `${httpCtx.className}.${httpCtx.methodName}` : void 0;
     const payload = {
       message,
       context: "KeycloakClient",
@@ -363,10 +370,10 @@ var KeycloakClient = class {
   async getAccessToken() {
     const method = "getAccessToken";
     this.log("debug", `${method} - Start`, method);
-    const now = Date.now();
-    if (this.tokenCache && now < this.tokenCache.expiresAt) {
+    const cached = await this.cacheProvider.get(TOKEN_CACHE_KEY);
+    if (cached) {
       this.log("debug", `${method} - Returning cached token`, method);
-      return this.tokenCache.token;
+      return cached;
     }
     if (this.tokenPromise) {
       this.log("debug", `${method} - Waiting for existing token request`, method);
@@ -375,8 +382,8 @@ var KeycloakClient = class {
     this.tokenPromise = (async () => {
       try {
         const tokenResponse = await this.requestToken();
-        const expiresAt = this.config.tokenCacheTtl ? Date.now() + this.config.tokenCacheTtl : Date.now() + (tokenResponse.expires_in - 60) * 1e3;
-        this.tokenCache = { token: tokenResponse.access_token, expiresAt };
+        const ttlSeconds = this.config.tokenCacheTtl ? Math.floor(this.config.tokenCacheTtl / 1e3) : tokenResponse.expires_in - 60;
+        await this.cacheProvider.set(TOKEN_CACHE_KEY, tokenResponse.access_token, ttlSeconds);
         this.log("debug", `${method} - Token obtained and cached`, method);
         return tokenResponse.access_token;
       } finally {
@@ -479,8 +486,8 @@ var KeycloakClient = class {
           logContext: { className: "KeycloakClient", methodName: method }
         }
       });
-      const expiresAt = this.config.tokenCacheTtl ? Date.now() + this.config.tokenCacheTtl : Date.now() + (response.data.expires_in - 60) * 1e3;
-      this.tokenCache = { token: response.data.access_token, expiresAt };
+      const ttlSeconds = this.config.tokenCacheTtl ? Math.floor(this.config.tokenCacheTtl / 1e3) : response.data.expires_in - 60;
+      await this.cacheProvider.set(TOKEN_CACHE_KEY, response.data.access_token, ttlSeconds);
       this.log("debug", `${method} - Success`, method);
       return response.data;
     } catch (err) {
@@ -550,12 +557,8 @@ var KeycloakClient = class {
       });
     }
   }
-  clearTokenCache() {
-    this.tokenCache = null;
-  }
-  static maskToken(token, visibleChars = 8) {
-    if (!token || typeof token !== "string") return "";
-    return token.length <= visibleChars ? token : `${token.slice(0, visibleChars)}...`;
+  async clearTokenCache() {
+    await this.cacheProvider.del(TOKEN_CACHE_KEY);
   }
   static scopesToString(scopes) {
     if (!scopes) return "openid profile email";
@@ -566,7 +569,9 @@ KeycloakClient = __decorateClass([
   (0, import_common.Injectable)(),
   __decorateParam(1, (0, import_common.Inject)(import_http_client.HTTP_PROVIDER)),
   __decorateParam(2, (0, import_common.Optional)()),
-  __decorateParam(2, (0, import_common.Inject)(import_logger.LOGGER_PROVIDER))
+  __decorateParam(2, (0, import_common.Inject)(import_logger.LOGGER_PROVIDER)),
+  __decorateParam(3, (0, import_common.Optional)()),
+  __decorateParam(3, (0, import_common.Inject)(import_cache2.CACHE_PROVIDER))
 ], KeycloakClient);
 
 // src/keycloak.http.interceptor.ts
@@ -711,11 +716,12 @@ var KeycloakModule = class {
         { provide: KEYCLOAK_CONFIG, useValue: config },
         {
           provide: KEYCLOAK_CLIENT,
-          useFactory: (cfg, httpProvider, logger) => new KeycloakClient(cfg, httpProvider, logger),
+          useFactory: (cfg, httpProvider, logger, cacheProvider) => new KeycloakClient(cfg, httpProvider, logger, cacheProvider),
           inject: [
             KEYCLOAK_CONFIG,
             import_http_client2.HTTP_PROVIDER,
-            { token: import_logger2.LOGGER_PROVIDER, optional: true }
+            { token: import_logger2.LOGGER_PROVIDER, optional: true },
+            { token: import_cache3.CACHE_PROVIDER, optional: true }
           ]
         },
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adatechnology/auth-keycloak",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "publishConfig": {
     "access": "public"
   },
@@ -11,7 +11,8 @@
     "dist"
   ],
   "dependencies": {
-    "@adatechnology/http-client": "0.0.7",
+    "@adatechnology/cache": "0.0.7",
+    "@adatechnology/http-client": "0.0.8",
     "@adatechnology/logger": "0.0.6"
   },
   "peerDependencies": {