@adatechnology/auth-keycloak 0.0.1 → 0.0.3

package/README.md

@@ -72,6 +72,52 @@ Notas
 - 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.
 
+## Autorização (decorator @Roles)
+
+O pacote agora fornece um decorator `@Roles()` e um `RolesGuard` para uso nas rotas do NestJS. Exemplos:
+
+```ts
+import { Controller, Get, UseGuards } from "@nestjs/common";
+import { Roles } from "@adatechnology/auth-keycloak";
+import { RolesGuard } from "@adatechnology/auth-keycloak";
+
+@Controller("secure")
+@UseGuards(RolesGuard)
+export class SecureController {
+  @Get("admin")
+  @Roles("admin") // aceita um ou mais roles (OR por padrão)
+  adminOnly() {
+    return { ok: true };
+  }
+
+  @Get("team")
+  @Roles({ roles: ["manager", "lead"], mode: "all" }) // requer ambos (AND)
+  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' }`.
+
+## 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:
+
+```ts
+import { KeycloakError } from "@adatechnology/auth-keycloak";
+
+try {
+  await keycloakClient.getUserInfo(token);
+} catch (e) {
+  if (e instanceof KeycloakError) {
+    // tratar problema específico de Keycloak
+    console.error(e.statusCode, e.details);
+  }
+  throw e;
+}
+```
+
 Contribuições
 
 Relate issues/PRs no repositório principal. Mantenha compatibilidade com o padrão usado pelo `HttpModule`.

package/dist/errors/keycloak-error.d.ts

@@ -0,0 +1,11 @@
+export declare class KeycloakError extends Error {
+    readonly statusCode?: number;
+    readonly details?: unknown;
+    readonly keycloakError?: string;
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        details?: unknown;
+        keycloakError?: string;
+    });
+}
+export default KeycloakError;

package/dist/errors/keycloak-error.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeycloakError = void 0;
+class KeycloakError extends Error {
+    statusCode;
+    details;
+    keycloakError;
+    constructor(message, opts) {
+        super(message);
+        this.name = "KeycloakError";
+        this.statusCode = opts?.statusCode;
+        this.details = opts?.details;
+        this.keycloakError = opts?.keycloakError;
+        // maintain proper prototype chain
+        Object.setPrototypeOf(this, KeycloakError.prototype);
+    }
+}
+exports.KeycloakError = KeycloakError;
+exports.default = KeycloakError;
+//# sourceMappingURL=keycloak-error.js.map

package/dist/errors/keycloak-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keycloak-error.js","sourceRoot":"","sources":["../../src/errors/keycloak-error.ts"],"names":[],"mappings":";;;AAAA,MAAa,aAAc,SAAQ,KAAK;IACtB,UAAU,CAAU;IACpB,OAAO,CAAW;IAClB,aAAa,CAAU;IAEvC,YACE,OAAe,EACf,IAAyE;QAEzE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,IAAI,EAAE,UAAU,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,OAAO,CAAC;QAC7B,IAAI,CAAC,aAAa,GAAG,IAAI,EAAE,aAAa,CAAC;QACzC,kCAAkC;QAClC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACvD,CAAC;CACF;AAjBD,sCAiBC;AAED,kBAAe,aAAa,CAAC"}

package/dist/index.d.ts

@@ -1,65 +1,6 @@
-import { DynamicModule } from '@nestjs/common';
-import { AxiosRequestConfig, AxiosInstance } from 'axios';
-
-/**
- * Keycloak token response
- */
-interface KeycloakTokenResponse {
-    access_token: string;
-    expires_in: number;
-    refresh_expires_in: number;
-    refresh_token: string;
-    token_type: string;
-    'not-before-policy': number;
-    session_state: string;
-    scope: string;
-}
-/**
- * Keycloak client credentials
- */
-interface KeycloakCredentials {
-    clientId: string;
-    clientSecret: string;
-    username?: string;
-    password?: string;
-    grantType: 'client_credentials' | 'password';
-}
-/**
- * Keycloak configuration
- */
-interface KeycloakConfig {
-    baseUrl: string;
-    realm: string;
-    credentials: KeycloakCredentials;
-}
-/**
- * Keycloak client interface
- */
-interface KeycloakClientInterface {
-    /**
-     * Get access token
-     */
-    getAccessToken(): Promise<string>;
-    /**
-     * Refresh access token
-     */
-    refreshToken(refreshToken: string): Promise<KeycloakTokenResponse>;
-    /**
-     * Validate token
-     */
-    validateToken(token: string): Promise<boolean>;
-    /**
-     * Get user info
-     */
-    getUserInfo(token: string): Promise<any>;
-}
-
-declare class KeycloakModule {
-    static forRoot(config: KeycloakConfig, httpConfig?: AxiosRequestConfig | AxiosInstance): DynamicModule;
-}
-
-declare const KEYCLOAK_CONFIG = "KEYCLOAK_CONFIG";
-declare const KEYCLOAK_CLIENT = "KEYCLOAK_CLIENT";
-declare const KEYCLOAK_HTTP_INTERCEPTOR = "KEYCLOAK_HTTP_INTERCEPTOR";
-
-export { KEYCLOAK_CLIENT, KEYCLOAK_CONFIG, KEYCLOAK_HTTP_INTERCEPTOR, KeycloakClientInterface, KeycloakConfig, KeycloakModule, KeycloakTokenResponse };
+export { KeycloakModule } from "./keycloak.module";
+export { KEYCLOAK_CONFIG, KEYCLOAK_CLIENT, KEYCLOAK_HTTP_INTERCEPTOR, } from "./keycloak.token";
+export type { KeycloakConfig, KeycloakClientInterface, KeycloakTokenResponse, } from "./keycloak.interface";
+export { Roles } from "./roles.decorator";
+export { RolesGuard } from "./roles.guard";
+export { KeycloakError } from "./errors/keycloak-error";