@adatechnology/auth-keycloak 0.1.0 → 0.1.2

package/README.md

@@ -129,66 +129,153 @@ Resultado no log:
 [MyController.getToken][InMemoryCacheProvider.set] → token cached
 ```
 
-### BearerTokenGuard — autenticação B2B via introspecção
+### Contrato de headers (Kong → API)
+
+```
+Authorization: Bearer <service_token>   → identidade do chamador (B2B)
+X-Access-Token: <user_jwt>              → token original do usuário (B2C)
+```
+
+Kong valida o JWT do usuário via JWKS (local, zero chamadas ao Keycloak por request) e injeta os dois headers antes de encaminhar a request ao API.
+
+---
+
+### Guards
 
-Valida que o header `Authorization: Bearer <token>` contém um token ativo chamando
-`POST /token/introspect` no Keycloak. Use sempre em conjunto com `RolesGuard` em rotas B2B.
+| Guard | Valida | Quando usar |
+|---|---|---|
+| `B2CGuard` | `X-Access-Token` presente | Rota exclusiva de usuários via Kong |
+| `B2BGuard` | `Authorization` via introspection | Rota exclusiva de serviços internos |
+| `ApiAuthGuard` | Detecta path e delega | Rota acessível pelos dois paths |
+| `RolesGuard` | Roles no JWT correto | Sempre junto a um guard acima |
+| `BearerTokenGuard` | `Authorization` via introspection | Nível baixo; prefira `B2BGuard` |
+
+**Guard order matters** — guards de autenticação devem vir antes de `RolesGuard`.
+
+---
+
+### Decorators
+
+#### `@AuthUser(param?)`
+Extrai claim do token em `X-Access-Token`. Padrão: claim configurado em `userId` (default `sub`). Decodificação local, sem I/O.
 
 ```ts
-import { Controller, Headers, Post, UseGuards } from "@nestjs/common";
-import { BearerTokenGuard, Roles, RolesGuard } from "@adatechnology/auth-keycloak";
-
-@Controller("orders")
-export class OrdersController {
-  @Post()
-  @Roles("manage-requests")
-  @UseGuards(BearerTokenGuard, RolesGuard)
-  create(@Headers("x-user-id") keycloakId: string) {}
-}
+@AuthUser()                                           // sub (default)
+@AuthUser('email')                                    // claim único
+@AuthUser(['preferred_username', 'email', 'sub'])     // primeiro não-vazio
+@AuthUser({ claim: 'email', header: 'x-user-jwt' }) // header customizado por rota
 ```
 
-**Por que dois guards em sequência?**
+#### `@CallerToken(param?)`
+Extrai claim do token em `Authorization`. Padrão: claim configurado em `callerId` (default `azp`).
 
-| Guard | Mecanismo | HTTP? | Falha |
-|---|---|---|---|
-| `BearerTokenGuard` | `POST /token/introspect` ao Keycloak | Sim | 401 — token inativo/expirado/forjado |
-| `RolesGuard` | Decode local do payload JWT | Não | 403 — permissão insuficiente |
+```ts
+@CallerToken()                                              // azp (default)
+@CallerToken('sub')                                         // claim único
+@CallerToken(['client_id', 'azp'])                          // primeiro não-vazio
+@CallerToken({ header: 'x-service-token', claim: 'azp' }) // header customizado
+```
 
-O `RolesGuard` sozinho **não é seguro** para autenticação: ele apenas decodifica o payload JWT
-sem verificar a assinatura, o que significa que um token forjado passaria. O `BearerTokenGuard`
-é quem garante autenticidade via introspecção.
+#### `@AccessToken(header?)`
+Retorna o JWT bruto do header B2C. Use quando precisar de claims não-string ou repassar o token.
 
-### Autorização com @Roles
+```ts
+@AccessToken()              // header B2C padrão
+@AccessToken('x-user-jwt')  // header customizado
+```
+
+#### `@Roles(...)`
+Declara roles necessárias. Sempre usado com `RolesGuard`.
 
 ```ts
-import { Controller, Get, UseGuards } from "@nestjs/common";
-import { Roles, RolesGuard } from "@adatechnology/auth-keycloak";
-
-@Controller("secure")
-export class SecureController {
-  @Get("public")
-  @UseGuards(RolesGuard)
-  public() {
-    return { ok: true };
-  }
+@Roles('user-manager')
+@Roles({ roles: ['admin', 'user-manager'], mode: 'any' })  // qualquer (default)
+@Roles({ roles: ['admin', 'user-manager'], mode: 'all' })  // todas
+```
 
-  @Get("admin")
-  @UseGuards(RolesGuard)
-  @Roles("admin")
-  adminOnly() {
-    return { ok: true };
-  }
+---
 
-  @Get("team")
-  @UseGuards(RolesGuard)
-  @Roles({ roles: ["manager", "lead"], mode: "all" }) // AND — requer ambas as roles
-  teamOnly() {
-    return { ok: true };
-  }
+### Exemplos de uso
+
+**B2C — usuário via Kong:**
+```ts
+@Get('me')
+@Roles('user-manager')
+@UseGuards(B2CGuard, RolesGuard)
+async getMe(
+  @AuthUser() id: string,
+  @AuthUser('email') email: string,
+  @AuthUser(['preferred_username', 'email']) name: string,
+  @AccessToken() rawToken: string,
+) {
+  return { id, email, name };
 }
 ```
 
-O `RolesGuard` extrai roles de `realm_access.roles` e `resource_access[clientId].roles` do JWT.
+**B2B — serviço interno:**
+```ts
+@Post('internal/notify')
+@Roles('send-notifications')
+@UseGuards(B2BGuard, RolesGuard)
+async notify(
+  @CallerToken() caller: string,  // 'domestic-backend-bff'
+) {
+  return { caller };
+}
+```
+
+**Ambos os paths:**
+```ts
+@Get(':id')
+@Roles('user-manager')
+@UseGuards(ApiAuthGuard, RolesGuard)
+async findById(
+  @Param('id') id: string,
+  @AuthUser() userId: string,    // vazio no B2B-only path
+  @CallerToken() caller: string,
+) { ... }
+```
+
+---
+
+### Configuração de headers e claims
+
+Configurável via env ou `forRoot()`. Prioridade: `forRoot()` > `process.env` > default.
+
+**Env vars:**
+```env
+KEYCLOAK_B2C_TOKEN_HEADER=x-access-token        # header do user JWT
+KEYCLOAK_B2B_TOKEN_HEADER=authorization         # header do service token
+KEYCLOAK_USER_ID_CLAIM=sub                      # claim(s) para user ID (comma-separated)
+KEYCLOAK_CALLER_ID_CLAIM=azp                    # claim(s) para caller ID (comma-separated)
+```
+
+**`forRoot()` (sobrescreve env):**
+```ts
+KeycloakModule.forRoot({
+  ...
+  headers: { b2cToken: 'x-access-token', b2bToken: 'authorization' },
+  claims: {
+    userId: ['preferred_username', 'email', 'sub'],  // string ou string[]
+    callerId: ['client_id', 'azp'],
+  },
+})
+```
+
+---
+
+### BearerTokenGuard — autenticação B2B via introspecção
+
+Valida `Authorization: Bearer <token>` chamando `POST /token/introspect` no Keycloak.
+
+| Guard | Mecanismo | HTTP? | Falha |
+|---|---|---|---|
+| `BearerTokenGuard` | `POST /token/introspect` | Sim | 401 |
+| `RolesGuard` | Decode local do payload | Não | 403 |
+
+O `RolesGuard` sozinho **não é seguro** — ele decodifica sem verificar assinatura.
+
+---
 
 ### Tratamento de erros
 
@@ -213,6 +300,10 @@ try {
 | `KEYCLOAK_REALM` | `BACKEND` |
 | `KEYCLOAK_CLIENT_ID` | `backend-api` |
 | `KEYCLOAK_CLIENT_SECRET` | `backend-api-secret` |
+| `KEYCLOAK_B2C_TOKEN_HEADER` | `x-access-token` |
+| `KEYCLOAK_B2B_TOKEN_HEADER` | `authorization` |
+| `KEYCLOAK_USER_ID_CLAIM` | `sub` |
+| `KEYCLOAK_CALLER_ID_CLAIM` | `azp` |
 
 ### Notas
 

package/dist/index.d.ts

@@ -44,6 +44,42 @@ interface KeycloakConfig {
      * determine how long to cache the access token instead of deriving TTL from the token's expires_in.
      */
     tokenCacheTtl?: number;
+    /**
+     * Header names for B2C and B2B token flows.
+     * Overrides process.env values when provided.
+     *
+     * Env equivalents:
+     *   KEYCLOAK_B2C_TOKEN_HEADER (default: 'x-access-token')
+     *   KEYCLOAK_B2B_TOKEN_HEADER (default: 'authorization')
+     */
+    headers?: {
+        /** Header carrying the user JWT forwarded by Kong. */
+        b2cToken?: string;
+        /** Header carrying the service account token. */
+        b2bToken?: string;
+    };
+    /**
+     * JWT claim names used to identify users and callers.
+     * Overrides process.env values when provided.
+     *
+     * Env equivalents:
+     *   KEYCLOAK_USER_ID_CLAIM   (default: 'sub')
+     *   KEYCLOAK_CALLER_ID_CLAIM (default: 'azp')
+     */
+    claims?: {
+        /**
+         * Claim name(s) for the user identifier (from the B2C token).
+         * When an array, the first non-empty value found in the JWT is used.
+         * Env: KEYCLOAK_USER_ID_CLAIM (comma-separated). Default: 'sub'
+         */
+        userId?: string | string[];
+        /**
+         * Claim name(s) for the calling client identifier (from the B2B token).
+         * When an array, the first non-empty value found in the JWT is used.
+         * Env: KEYCLOAK_CALLER_ID_CLAIM (comma-separated). Default: 'azp'
+         */
+        callerId?: string | string[];
+    };
 }
 /**
  * Keycloak client interface
@@ -121,30 +157,262 @@ declare const KEYCLOAK_PROVIDER = "KEYCLOAK_PROVIDER";
 
 type RolesMode = "any" | "all";
 type RolesType = "realm" | "client" | "both";
+interface TokenRolesOptions {
+    /** Header name where the JWT lives. E.g. 'x-access-token', 'authorization'. */
+    header: string;
+    /** Roles required from that token. */
+    roles: string[];
+    /** Match mode. Default: 'any' (at least one role must match). */
+    mode?: RolesMode;
+    /**
+     * If true, strips the 'Bearer ' prefix before decoding.
+     * Auto-detected when omitted: stripped when header is 'authorization'.
+     */
+    bearer?: boolean;
+}
 type RolesOptions = {
     roles: string[];
     mode?: RolesMode;
     type?: RolesType;
 };
 /**
- * Decorator to declare required roles for a route or controller.
- * Accepts either a list of strings or a single options object.
- * Examples:
+ * Declares required roles without specifying the token source.
+ * RolesGuard resolves the token automatically:
+ *   - X-Access-Token present → reads from user JWT (B2C)
+ *   - Authorization only     → reads from service JWT (B2B)
+ *
+ * @example
  *  @Roles('admin')
- *  @Roles('admin','editor')
- *  @Roles(['admin','editor'])
- *  @Roles({ roles: ['a','b'], mode: 'all', type: 'client' })
+ *  @Roles('admin', 'editor')
+ *  @Roles({ roles: ['admin', 'editor'], mode: 'all' })
  */
 declare function Roles(...args: Array<string | string[] | RolesOptions>): _nestjs_common.CustomDecorator<string>;
+/**
+ * Declares roles that must be present in the **user JWT** (`X-Access-Token`).
+ * Checked independently from B2BRoles — both must pass when both are declared.
+ *
+ * Use when the route requires a specific user role regardless of which service called it.
+ *
+ * @example
+ *  @B2CRoles('user-manager')
+ *  @B2CRoles({ roles: ['admin', 'user-manager'], mode: 'all' })
+ */
+declare function B2CRoles(...args: Array<string | string[] | RolesOptions>): _nestjs_common.CustomDecorator<string>;
+/**
+ * Declares roles that must be present in the **service token** (`Authorization`).
+ * Checked independently from B2CRoles — both must pass when both are declared.
+ *
+ * Use when the route requires the calling service to have a specific role,
+ * regardless of which user triggered the request.
+ *
+ * @example
+ *  @B2BRoles('manage-requests')
+ *  @B2BRoles({ roles: ['manage-requests', 'send-notifications'], mode: 'any' })
+ */
+declare function B2BRoles(...args: Array<string | string[] | RolesOptions>): _nestjs_common.CustomDecorator<string>;
+/**
+ * Declares role requirements tied to a specific JWT header.
+ * Fully dynamic — works with any header that carries a JWT.
+ *
+ * Multiple uses are accumulated (AND logic): every @TokenRoles block must pass.
+ * Uses Reflector.getAllAndMerge internally, so stacking works correctly.
+ *
+ * @example
+ * // Verify user roles from X-Access-Token AND service roles from Authorization:
+ * @TokenRoles({ header: 'x-access-token', roles: ['user-manager'] })
+ * @TokenRoles({ header: 'authorization',  roles: ['manage-requests'] })
+ * @UseGuards(B2BGuard, B2CGuard, RolesGuard)
+ *
+ * // Custom token header with ALL mode:
+ * @TokenRoles({ header: 'x-partner-token', roles: ['partner-admin', 'partner-api'], mode: 'all' })
+ * @UseGuards(RolesGuard)
+ */
+declare function TokenRoles(options: TokenRolesOptions): _nestjs_common.CustomDecorator<string>;
 
+/**
+ * Guard that enforces role requirements declared by @Roles, @B2CRoles, and @B2BRoles.
+ *
+ * Three decorator modes:
+ *
+ * @Roles('x')      — auto-detect token source:
+ *                    X-Access-Token present → read from user JWT (B2C)
+ *                    Authorization only     → read from service JWT (B2B)
+ *
+ * @B2CRoles('x')   — always check the user JWT in X-Access-Token
+ * @B2BRoles('x')   — always check the service JWT in Authorization
+ *
+ * When @B2CRoles AND @B2BRoles are both declared, BOTH checks must pass.
+ * This allows expressing: "the calling service must have role X AND the user must have role Y".
+ */
 declare class RolesGuard implements CanActivate {
     private readonly reflector;
     private readonly config?;
     constructor(reflector: Reflector, config?: KeycloakConfig);
-    canActivate(context: ExecutionContext): boolean | Promise<boolean>;
+    canActivate(context: ExecutionContext): boolean;
+    private getMeta;
+    private extractRoles;
+    private assertRoles;
     private decodeJwtPayload;
 }
 
+/**
+ * B2B Guard — service-to-service routes (e.g. BFF → API, Worker → API).
+ *
+ * The caller must send a valid service account token (client_credentials)
+ * in the Authorization header. Delegates full token validation to
+ * BearerTokenGuard (Keycloak introspection).
+ *
+ * The caller is also expected to forward X-User-Id so the API knows which
+ * end-user context the call belongs to.
+ *
+ * Use for routes that are ONLY called by internal services, not by end users.
+ *
+ * @example
+ * ```ts
+ * @Post('internal/notify')
+ * @Roles('send-notifications')
+ * @UseGuards(B2BGuard, RolesGuard)
+ * async notify(@AuthUser() keycloakId: string) { ... }
+ * ```
+ */
+declare class B2BGuard implements CanActivate {
+    private readonly bearerTokenGuard;
+    constructor(bearerTokenGuard: BearerTokenGuard);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+
+/**
+ * B2C Guard — validates user context on routes that receive Kong-forwarded requests.
+ *
+ * Kong validates the user JWT (JWKS local) and injects:
+ *   - `Authorization: Bearer <service_token>` — the calling service identity (B2B)
+ *   - `X-Access-Token: <user_token>`          — the original user token (B2C context)
+ *   - `X-User-Id`                             — keycloak sub (extracted by Kong)
+ *   - `X-User-Roles`                          — realm roles CSV (extracted by Kong)
+ *
+ * This guard asserts the user context headers are present.
+ * It does NOT re-validate the user token — that is Kong's responsibility.
+ *
+ * Pair with B2BGuard (or ApiAuthGuard) + RolesGuard for full auth.
+ *
+ * @example
+ * ```ts
+ * @Get('me')
+ * @Roles('user-manager')
+ * @UseGuards(B2CGuard, RolesGuard)
+ * async getMe(@AuthUser() keycloakId: string) { ... }
+ * ```
+ */
+declare class B2CGuard implements CanActivate {
+    canActivate(context: ExecutionContext): boolean;
+}
+
+/**
+ * ApiAuthGuard — composite guard for routes that accept both paths.
+ *
+ * Detects which path the request is coming from and delegates accordingly:
+ *
+ * - **B2B path** (Authorization header present):
+ *   Service-to-service call (e.g. BFF → API). Delegates to B2BGuard,
+ *   which validates the service account token via BearerTokenGuard.
+ *
+ * - **B2C path** (X-User-Id header present, no Authorization):
+ *   User call routed by Kong. Delegates to B2CGuard,
+ *   which asserts Kong identity headers are present.
+ *
+ * Use when the same route must be reachable both from Kong (users) and
+ * from internal services (BFF, Worker). If the route is exclusive to one
+ * path, prefer B2BGuard or B2CGuard directly for explicit intent.
+ *
+ * @example
+ * ```ts
+ * @Get('me')
+ * @Roles('user-manager')
+ * @UseGuards(ApiAuthGuard, RolesGuard)
+ * async getMe(@AuthUser() keycloakId: string) { ... }
+ * ```
+ */
+declare class ApiAuthGuard implements CanActivate {
+    private readonly b2bGuard;
+    private readonly b2cGuard;
+    constructor(b2bGuard: B2BGuard, b2cGuard: B2CGuard);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+
+interface AuthUserOptions {
+    /**
+     * Override the header to read the B2C token from.
+     * Defaults to the configured B2C token header (env: KEYCLOAK_B2C_TOKEN_HEADER).
+     */
+    header?: string;
+    /**
+     * Claim name(s) to extract from the JWT payload.
+     * First non-empty value wins. Defaults to configured userId claim(s).
+     */
+    claim?: string | string[];
+}
+interface CallerTokenOptions {
+    /**
+     * Override the header to read the B2B token from.
+     * Defaults to the configured B2B token header (env: KEYCLOAK_B2B_TOKEN_HEADER).
+     */
+    header?: string;
+    /**
+     * Claim name(s) to extract from the JWT payload.
+     * First non-empty value wins. Defaults to configured callerId claim(s).
+     */
+    claim?: string | string[];
+}
+/**
+ * Extracts a claim from the user JWT forwarded by Kong in the B2C token header.
+ *
+ * Claims are decoded locally — no extra I/O.
+ *
+ * @param param - Claim name, array of claim names (first non-empty wins),
+ *                or `{ header, claim }` to fully customize both.
+ *
+ * @example
+ * ```ts
+ * @AuthUser()                                          // sub (default)
+ * @AuthUser('email')                                   // single claim
+ * @AuthUser(['preferred_username', 'email'])            // first non-empty
+ * @AuthUser({ claim: 'email', header: 'x-user-jwt' }) // custom header
+ * ```
+ */
+declare const AuthUser: (...dataOrPipes: (string | string[] | AuthUserOptions | _nestjs_common.PipeTransform<any, any> | _nestjs_common.Type<_nestjs_common.PipeTransform<any, any>>)[]) => ParameterDecorator;
+/**
+ * Extracts a claim from the service token in the B2B token header.
+ *
+ * Use this to identify the calling service.
+ *
+ * @param param - Claim name, array of claim names (first non-empty wins),
+ *                or `{ header, claim }` to fully customize both.
+ *
+ * @example
+ * ```ts
+ * @CallerToken()                                              // azp (default)
+ * @CallerToken('sub')                                         // single claim
+ * @CallerToken(['client_id', 'azp'])                          // first non-empty
+ * @CallerToken({ header: 'x-service-token', claim: 'azp' }) // custom header
+ * ```
+ */
+declare const CallerToken: (...dataOrPipes: (string | string[] | CallerTokenOptions | _nestjs_common.PipeTransform<any, any> | _nestjs_common.Type<_nestjs_common.PipeTransform<any, any>>)[]) => ParameterDecorator;
+/**
+ * Extracts the raw B2C token header value (full user JWT string).
+ *
+ * Use this when you need the full token to pass downstream or inspect
+ * non-string claims (arrays, objects). For scalar claims prefer `@AuthUser(claim)`.
+ *
+ * @param header - Override the header name. Defaults to configured B2C token header.
+ *
+ * @example
+ * ```ts
+ * @AccessToken()                    // reads from default B2C header
+ * @AccessToken('x-user-jwt')        // reads from custom header
+ * ```
+ */
+declare const AccessToken: (...dataOrPipes: (string | _nestjs_common.PipeTransform<any, any> | _nestjs_common.Type<_nestjs_common.PipeTransform<any, any>>)[]) => ParameterDecorator;
+
 declare class KeycloakError extends Error {
     readonly statusCode?: number;
     readonly details?: unknown;
@@ -156,4 +424,43 @@ declare class KeycloakError extends Error {
     });
 }
 
-export { BearerTokenGuard, KEYCLOAK_CLIENT, KEYCLOAK_CONFIG, KEYCLOAK_HTTP_INTERCEPTOR, KEYCLOAK_PROVIDER, type KeycloakClientInterface, type KeycloakConfig, KeycloakError, KeycloakModule, type KeycloakProviderInterface, type KeycloakTokenResponse, Roles, RolesGuard };
+/**
+ * Runtime-configurable header names and JWT claim names for the B2B/B2C auth flow.
+ *
+ * Priority (highest → lowest):
+ *   1. KeycloakModule.forRoot({ headers, claims }) — programmatic config
+ *   2. process.env vars — set in .env files
+ *   3. Built-in defaults
+ *
+ * Environment variables:
+ *   KEYCLOAK_B2C_TOKEN_HEADER  — header for the user JWT       (default: x-access-token)
+ *   KEYCLOAK_B2B_TOKEN_HEADER  — header for the service token  (default: authorization)
+ *   KEYCLOAK_USER_ID_CLAIM     — claim(s) for user ID, comma-separated  (default: sub)
+ *   KEYCLOAK_CALLER_ID_CLAIM   — claim(s) for caller ID, comma-separated (default: azp)
+ *
+ * Multiple claims example (first non-empty value wins):
+ *   KEYCLOAK_USER_ID_CLAIM=preferred_username,email,sub
+ *   KEYCLOAK_CALLER_ID_CLAIM=client_id,azp
+ */
+interface TokenHeaderConfig {
+    /** Header name for the B2C user JWT forwarded by Kong. Default: 'x-access-token' */
+    b2cToken?: string;
+    /** Header name for the B2B service account token. Default: 'authorization' */
+    b2bToken?: string;
+}
+interface TokenClaimConfig {
+    /**
+     * Claim name(s) for the user identifier (from the B2C token).
+     * When an array, the first non-empty value found in the JWT is returned.
+     * Default: ['sub']
+     */
+    userId?: string | string[];
+    /**
+     * Claim name(s) for the caller/client identifier (from the B2B token).
+     * When an array, the first non-empty value found in the JWT is returned.
+     * Default: ['azp']
+     */
+    callerId?: string | string[];
+}
+
+export { AccessToken, ApiAuthGuard, AuthUser, type AuthUserOptions, B2BGuard, B2BRoles, B2CGuard, B2CRoles, BearerTokenGuard, CallerToken, type CallerTokenOptions, KEYCLOAK_CLIENT, KEYCLOAK_CONFIG, KEYCLOAK_HTTP_INTERCEPTOR, KEYCLOAK_PROVIDER, type KeycloakClientInterface, type KeycloakConfig, KeycloakError, KeycloakModule, type KeycloakProviderInterface, type KeycloakTokenResponse, Roles, RolesGuard, type TokenClaimConfig, type TokenHeaderConfig, TokenRoles, type TokenRolesOptions };

package/dist/index.js

@@ -68,7 +68,7 @@ var require_base_app_error = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.BaseAppError = void 0;
-    var BaseAppError3 = class extends Error {
+    var BaseAppError5 = class extends Error {
       code;
       status;
       context;
@@ -83,7 +83,7 @@ var require_base_app_error = __commonJS({
         (_a = capturable.captureStackTrace) == null ? void 0 : _a.call(capturable, this, this.constructor);
       }
     };
-    exports2.BaseAppError = BaseAppError3;
+    exports2.BaseAppError = BaseAppError5;
   }
 });
 
@@ -268,7 +268,15 @@ var require_dist = __commonJS({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AccessToken: () => AccessToken,
+  ApiAuthGuard: () => ApiAuthGuard,
+  AuthUser: () => AuthUser,
+  B2BGuard: () => B2BGuard,
+  B2BRoles: () => B2BRoles,
+  B2CGuard: () => B2CGuard,
+  B2CRoles: () => B2CRoles,
   BearerTokenGuard: () => BearerTokenGuard,
+  CallerToken: () => CallerToken,
   KEYCLOAK_CLIENT: () => KEYCLOAK_CLIENT,
   KEYCLOAK_CONFIG: () => KEYCLOAK_CONFIG,
   KEYCLOAK_HTTP_INTERCEPTOR: () => KEYCLOAK_HTTP_INTERCEPTOR,
@@ -276,7 +284,8 @@ __export(index_exports, {
   KeycloakError: () => KeycloakError,
   KeycloakModule: () => KeycloakModule,
   Roles: () => Roles,
-  RolesGuard: () => RolesGuard
+  RolesGuard: () => RolesGuard,
+  TokenRoles: () => TokenRoles
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -302,7 +311,7 @@ var KEYCLOAK_PROVIDER = "KEYCLOAK_PROVIDER";
 // package.json
 var package_default = {
   name: "@adatechnology/auth-keycloak",
-  version: "0.1.0",
+  version: "0.1.2",
   publishConfig: {
     access: "public"
   },
@@ -753,7 +762,19 @@ var import_core = require("@nestjs/core");
 // src/roles.decorator.ts
 var import_common4 = require("@nestjs/common");
 var ROLES_META_KEY = "roles";
+var B2C_ROLES_META_KEY = "roles:b2c";
+var B2B_ROLES_META_KEY = "roles:b2b";
+var TOKEN_ROLES_META_KEY = "roles:token";
 function Roles(...args) {
+  return (0, import_common4.SetMetadata)(ROLES_META_KEY, normalizeRolesOptions(args));
+}
+function B2CRoles(...args) {
+  return (0, import_common4.SetMetadata)(B2C_ROLES_META_KEY, normalizeRolesOptions(args));
+}
+function B2BRoles(...args) {
+  return (0, import_common4.SetMetadata)(B2B_ROLES_META_KEY, normalizeRolesOptions(args));
+}
+function normalizeRolesOptions(args) {
   let payload;
   if (args.length === 1 && typeof args[0] === "object" && !Array.isArray(args[0])) {
     payload = args[0];
@@ -765,72 +786,162 @@ function Roles(...args) {
   }
   payload.mode = payload.mode ?? "any";
   payload.type = payload.type ?? "both";
-  return (0, import_common4.SetMetadata)(ROLES_META_KEY, payload);
+  return payload;
+}
+function TokenRoles(options) {
+  const normalized = {
+    ...options,
+    header: options.header.toLowerCase(),
+    mode: options.mode ?? "any",
+    // auto-detect bearer stripping: true when header is 'authorization'
+    bearer: options.bearer ?? options.header.toLowerCase() === "authorization"
+  };
+  return (0, import_common4.SetMetadata)(TOKEN_ROLES_META_KEY, [normalized]);
 }
 
 // src/roles.guard.ts
 var import_shared2 = __toESM(require_dist());
+
+// src/keycloak.headers.ts
+var state = {
+  headers: {
+    b2cToken: parseEnvHeader("KEYCLOAK_B2C_TOKEN_HEADER", "x-access-token"),
+    b2bToken: parseEnvHeader("KEYCLOAK_B2B_TOKEN_HEADER", "authorization")
+  },
+  claims: {
+    userId: parseEnvClaims("KEYCLOAK_USER_ID_CLAIM", ["sub"]),
+    callerId: parseEnvClaims("KEYCLOAK_CALLER_ID_CLAIM", ["azp"])
+  }
+};
+function configureTokenHeaders(cfg) {
+  if (cfg.b2cToken) state.headers.b2cToken = cfg.b2cToken.toLowerCase();
+  if (cfg.b2bToken) state.headers.b2bToken = cfg.b2bToken.toLowerCase();
+}
+function configureTokenClaims(cfg) {
+  if (cfg.userId) state.claims.userId = normalizeClaims(cfg.userId);
+  if (cfg.callerId) state.claims.callerId = normalizeClaims(cfg.callerId);
+}
+function getB2CTokenHeader() {
+  return state.headers.b2cToken;
+}
+function getB2BTokenHeader() {
+  return state.headers.b2bToken;
+}
+function getUserIdClaims() {
+  return state.claims.userId;
+}
+function getCallerIdClaims() {
+  return state.claims.callerId;
+}
+function parseEnvHeader(key, fallback) {
+  return (process.env[key] ?? fallback).toLowerCase();
+}
+function parseEnvClaims(key, fallback) {
+  const raw = process.env[key];
+  if (!raw) return fallback;
+  return raw.split(",").map((c) => c.trim()).filter(Boolean);
+}
+function normalizeClaims(value) {
+  if (Array.isArray(value)) return value.filter(Boolean);
+  return value.split(",").map((c) => c.trim()).filter(Boolean);
+}
+
+// src/roles.guard.ts
 var RolesGuard = class {
   constructor(reflector, config) {
     this.reflector = reflector;
     this.config = config;
   }
   canActivate(context) {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
-    const meta = this.reflector.get(ROLES_META_KEY, context.getHandler()) || this.reflector.get(ROLES_META_KEY, context.getClass());
-    if (!meta || !meta.roles || meta.roles.length === 0) return true;
+    var _a, _b, _c, _d, _e, _f;
     const req = context.switchToHttp().getRequest();
-    const authHeader = ((_a = req.headers) == null ? void 0 : _a.authorization) || ((_b = req.headers) == null ? void 0 : _b.Authorization);
-    const token = authHeader ? String(authHeader).split(" ")[1] : (_c = req.query) == null ? void 0 : _c.token;
-    if (!token)
-      throw new import_shared2.BaseAppError({
-        message: "Authorization token not provided",
-        status: HTTP_STATUS.FORBIDDEN,
-        code: ROLES_ERROR_CODE.MISSING_TOKEN,
-        context: {}
-      });
-    const payload = this.decodeJwtPayload(token);
-    const availableRoles = /* @__PURE__ */ new Set();
-    if (((_d = payload == null ? void 0 : payload.realm_access) == null ? void 0 : _d.roles) && Array.isArray(payload.realm_access.roles)) {
-      payload.realm_access.roles.forEach((r) => availableRoles.add(r));
+    const b2cMeta = this.getMeta(B2C_ROLES_META_KEY, context);
+    const b2bMeta = this.getMeta(B2B_ROLES_META_KEY, context);
+    const genericMeta = this.getMeta(ROLES_META_KEY, context);
+    const tokenRules = this.reflector.getAllAndMerge(
+      TOKEN_ROLES_META_KEY,
+      [context.getHandler(), context.getClass()]
+    ) ?? [];
+    if (!b2cMeta && !b2bMeta && !genericMeta && tokenRules.length === 0) return true;
+    if (b2cMeta) {
+      const token = (_a = req.headers) == null ? void 0 : _a[getB2CTokenHeader()];
+      const roles = token ? this.extractRoles(token, "b2c") : /* @__PURE__ */ new Set();
+      this.assertRoles(roles, b2cMeta, "B2C (user)");
     }
-    const clientId = (_f = (_e = this.config) == null ? void 0 : _e.credentials) == null ? void 0 : _f.clientId;
-    if (clientId && ((_h = (_g = payload == null ? void 0 : payload.resource_access) == null ? void 0 : _g[clientId]) == null ? void 0 : _h.roles)) {
-      payload.resource_access[clientId].roles.forEach(
-        (r) => availableRoles.add(r)
-      );
+    if (b2bMeta) {
+      const raw = (_b = req.headers) == null ? void 0 : _b[getB2BTokenHeader()];
+      const token = raw == null ? void 0 : raw.split(" ")[1];
+      const roles = token ? this.extractRoles(token, "b2b") : /* @__PURE__ */ new Set();
+      this.assertRoles(roles, b2bMeta, "B2B (service)");
     }
-    if (meta.type === "both" && (payload == null ? void 0 : payload.resource_access)) {
-      Object.values(payload.resource_access).forEach((entry) => {
-        if ((entry == null ? void 0 : entry.roles) && Array.isArray(entry.roles)) {
-          entry.roles.forEach(
-            (r) => availableRoles.add(r)
-          );
+    if (genericMeta) {
+      const accessToken = (_c = req.headers) == null ? void 0 : _c[getB2CTokenHeader()];
+      if (accessToken) {
+        const roles = this.extractRoles(accessToken, "b2c");
+        this.assertRoles(roles, genericMeta, "B2C (user)");
+      } else {
+        const raw = (_d = req.headers) == null ? void 0 : _d[getB2BTokenHeader()];
+        const token = (raw == null ? void 0 : raw.split(" ")[1]) ?? ((_e = req.query) == null ? void 0 : _e.token);
+        if (!token) {
+          throw new import_shared2.BaseAppError({
+            message: "Authorization token not provided",
+            status: HTTP_STATUS.FORBIDDEN,
+            code: ROLES_ERROR_CODE.MISSING_TOKEN,
+            context: {}
+          });
         }
-      });
+        const roles = this.extractRoles(token, "b2b");
+        this.assertRoles(roles, genericMeta, "B2B (service)");
+      }
+    }
+    for (const rule of tokenRules) {
+      const raw = (_f = req.headers) == null ? void 0 : _f[rule.header];
+      const token = rule.bearer ? raw == null ? void 0 : raw.split(" ")[1] : raw;
+      const roles = token ? this.extractRoles(token, "b2c") : /* @__PURE__ */ new Set();
+      this.assertRoles(roles, { roles: rule.roles, mode: rule.mode ?? "any" }, `header:${rule.header}`);
     }
-    const required = meta.roles || [];
-    const hasMatch = required.map((r) => availableRoles.has(r));
-    const result = meta.mode === "all" ? hasMatch.every(Boolean) : hasMatch.some(Boolean);
-    if (!result)
+    return true;
+  }
+  // ── Helpers ───────────────────────────────────────────────────────────────
+  getMeta(key, ctx) {
+    return this.reflector.get(key, ctx.getHandler()) || this.reflector.get(key, ctx.getClass()) || void 0;
+  }
+  extractRoles(token, source) {
+    var _a, _b, _c, _d;
+    const payload = this.decodeJwtPayload(token);
+    const roles = /* @__PURE__ */ new Set();
+    if (((_a = payload == null ? void 0 : payload.realm_access) == null ? void 0 : _a.roles) && Array.isArray(payload.realm_access.roles)) {
+      payload.realm_access.roles.forEach((r) => roles.add(r));
+    }
+    if (source === "b2b" && (payload == null ? void 0 : payload.resource_access)) {
+      const clientId = (_c = (_b = this.config) == null ? void 0 : _b.credentials) == null ? void 0 : _c.clientId;
+      if (clientId && ((_d = payload.resource_access[clientId]) == null ? void 0 : _d.roles)) {
+        payload.resource_access[clientId].roles.forEach((r) => roles.add(r));
+      }
+    }
+    return roles;
+  }
+  assertRoles(available, meta, label) {
+    const hasMatch = meta.roles.map((r) => available.has(r));
+    const passed = meta.mode === "all" ? hasMatch.every(Boolean) : hasMatch.some(Boolean);
+    if (!passed) {
       throw new import_shared2.BaseAppError({
-        message: "Insufficient roles",
+        message: `Insufficient roles for ${label} token`,
         status: HTTP_STATUS.FORBIDDEN,
         code: ROLES_ERROR_CODE.INSUFFICIENT_ROLES,
-        context: { required }
+        context: { required: meta.roles, source: label }
       });
-    return true;
+    }
   }
   decodeJwtPayload(token) {
     try {
       const parts = token.split(".");
       if (parts.length < 2) return {};
-      const payload = parts[1];
+      const padded = parts[1].replace(/-/g, "+").replace(/_/g, "/");
       const BufferCtor = globalThis.Buffer;
       if (!BufferCtor) return {};
-      const decoded = BufferCtor.from(payload, "base64").toString("utf8");
-      return JSON.parse(decoded);
-    } catch (e) {
+      return JSON.parse(BufferCtor.from(padded, "base64").toString("utf8"));
+    } catch {
       return {};
     }
   }
@@ -845,6 +956,8 @@ RolesGuard = __decorateClass([
 // src/keycloak.module.ts
 var KeycloakModule = class {
   static forRoot(config, httpConfig) {
+    if (config.headers) configureTokenHeaders(config.headers);
+    if (config.claims) configureTokenClaims(config.claims);
     return {
       module: KeycloakModule,
       global: true,
@@ -900,9 +1013,172 @@ var KeycloakModule = class {
 KeycloakModule = __decorateClass([
   (0, import_common6.Module)({})
 ], KeycloakModule);
+
+// src/b2b.guard.ts
+var import_common7 = require("@nestjs/common");
+var B2BGuard = class {
+  constructor(bearerTokenGuard) {
+    this.bearerTokenGuard = bearerTokenGuard;
+  }
+  canActivate(context) {
+    return Promise.resolve(this.bearerTokenGuard.canActivate(context));
+  }
+};
+B2BGuard = __decorateClass([
+  (0, import_common7.Injectable)()
+], B2BGuard);
+
+// src/b2c.guard.ts
+var import_common8 = require("@nestjs/common");
+var import_shared3 = __toESM(require_dist());
+var B2CGuard = class {
+  canActivate(context) {
+    var _a;
+    const request = context.switchToHttp().getRequest();
+    const accessToken = (_a = request.headers) == null ? void 0 : _a[getB2CTokenHeader()];
+    if (accessToken) return true;
+    throw new import_shared3.BaseAppError({
+      message: "Missing X-Access-Token header. Route requires Kong-forwarded user authentication.",
+      status: HTTP_STATUS.UNAUTHORIZED,
+      code: BEARER_ERROR_CODE.MISSING_TOKEN,
+      context: {}
+    });
+  }
+};
+B2CGuard = __decorateClass([
+  (0, import_common8.Injectable)()
+], B2CGuard);
+
+// src/api-auth.guard.ts
+var import_common9 = require("@nestjs/common");
+var import_shared4 = __toESM(require_dist());
+var ApiAuthGuard = class {
+  constructor(b2bGuard, b2cGuard) {
+    this.b2bGuard = b2bGuard;
+    this.b2cGuard = b2cGuard;
+  }
+  async canActivate(context) {
+    var _a, _b;
+    const request = context.switchToHttp().getRequest();
+    const accessToken = (_a = request.headers) == null ? void 0 : _a[getB2CTokenHeader()];
+    if (accessToken) {
+      return this.b2cGuard.canActivate(context);
+    }
+    const authHeader = (_b = request.headers) == null ? void 0 : _b[getB2BTokenHeader()];
+    if (authHeader == null ? void 0 : authHeader.toLowerCase().startsWith("bearer ")) {
+      return this.b2bGuard.canActivate(context);
+    }
+    throw new import_shared4.BaseAppError({
+      message: "Unauthorized: missing X-Access-Token (Kong/B2C) or Authorization header (B2B)",
+      status: HTTP_STATUS.UNAUTHORIZED,
+      code: BEARER_ERROR_CODE.MISSING_TOKEN,
+      context: {}
+    });
+  }
+};
+ApiAuthGuard = __decorateClass([
+  (0, import_common9.Injectable)()
+], ApiAuthGuard);
+
+// src/auth-user.decorator.ts
+var import_common10 = require("@nestjs/common");
+var AuthUser = (0, import_common10.createParamDecorator)(
+  (param, ctx) => {
+    var _a;
+    const request = ctx.switchToHttp().getRequest();
+    const { header, claims } = resolveB2CParam(param);
+    const raw = (_a = request.headers) == null ? void 0 : _a[header];
+    const token = Array.isArray(raw) ? raw[0] : raw;
+    if (!token) return "";
+    return decodeJwtClaims(String(token), claims) ?? "";
+  }
+);
+var CallerToken = (0, import_common10.createParamDecorator)(
+  (param, ctx) => {
+    var _a;
+    const request = ctx.switchToHttp().getRequest();
+    const { header, claims } = resolveB2BParam(param);
+    const raw = (_a = request.headers) == null ? void 0 : _a[header];
+    const token = raw == null ? void 0 : raw.split(" ")[1];
+    if (!token) return "";
+    return decodeJwtClaims(token, claims) ?? "";
+  }
+);
+var AccessToken = (0, import_common10.createParamDecorator)(
+  (header, ctx) => {
+    var _a;
+    const request = ctx.switchToHttp().getRequest();
+    const h = (header == null ? void 0 : header.toLowerCase()) ?? getB2CTokenHeader();
+    const raw = (_a = request.headers) == null ? void 0 : _a[h];
+    return Array.isArray(raw) ? raw[0] : raw ?? "";
+  }
+);
+function resolveB2CParam(param) {
+  var _a;
+  if (!param) {
+    return { header: getB2CTokenHeader(), claims: getUserIdClaims() };
+  }
+  if (typeof param === "string") {
+    return { header: getB2CTokenHeader(), claims: [param] };
+  }
+  if (Array.isArray(param)) {
+    return { header: getB2CTokenHeader(), claims: param };
+  }
+  return {
+    header: ((_a = param.header) == null ? void 0 : _a.toLowerCase()) ?? getB2CTokenHeader(),
+    claims: param.claim ? normalizeClaims2(param.claim) : getUserIdClaims()
+  };
+}
+function resolveB2BParam(param) {
+  var _a;
+  if (!param) {
+    return { header: getB2BTokenHeader(), claims: getCallerIdClaims() };
+  }
+  if (typeof param === "string") {
+    return { header: getB2BTokenHeader(), claims: [param] };
+  }
+  if (Array.isArray(param)) {
+    return { header: getB2BTokenHeader(), claims: param };
+  }
+  return {
+    header: ((_a = param.header) == null ? void 0 : _a.toLowerCase()) ?? getB2BTokenHeader(),
+    claims: param.claim ? normalizeClaims2(param.claim) : getCallerIdClaims()
+  };
+}
+function normalizeClaims2(value) {
+  if (Array.isArray(value)) return value.filter(Boolean);
+  return value.split(",").map((c) => c.trim()).filter(Boolean);
+}
+function decodeJwtClaims(token, claims) {
+  try {
+    const parts = token.split(".");
+    if (parts.length < 2) return void 0;
+    const padded = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const BufferCtor = globalThis.Buffer;
+    if (!BufferCtor) return void 0;
+    const payload = JSON.parse(
+      BufferCtor.from(padded, "base64").toString("utf8")
+    );
+    for (const claim of claims) {
+      const value = payload[claim];
+      if (typeof value === "string" && value.length > 0) return value;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AccessToken,
+  ApiAuthGuard,
+  AuthUser,
+  B2BGuard,
+  B2BRoles,
+  B2CGuard,
+  B2CRoles,
   BearerTokenGuard,
+  CallerToken,
   KEYCLOAK_CLIENT,
   KEYCLOAK_CONFIG,
   KEYCLOAK_HTTP_INTERCEPTOR,
@@ -910,5 +1186,6 @@ KeycloakModule = __decorateClass([
   KeycloakError,
   KeycloakModule,
   Roles,
-  RolesGuard
+  RolesGuard,
+  TokenRoles
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adatechnology/auth-keycloak",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "publishConfig": {
     "access": "public"
   },