feat(user.controller): add new endpoints for managing claims and roles

Refactor the existing `setClaims` endpoint to `setRoleClaims` to distinguish between generic
claims and role-based claims. Introduce a new `setClaims` endpoint for setting generic claims.
Add corresponding get endpoints for retrieving both roles and claims, enhancing clarity in
API usage.

docs(README): update documentation with new role claims functionality

Update the README to reflect changes in API calls such as `setClaimsRoleBase` and details for
handling custom claims with `rolesClaimKey`. Clarify examples provided for role-based access
control to match the updated function signatures.

test(app-local-validation.e2e-spec.ts): enhance e2e tests with local environment variable support

Introduce `FIREBASE_TEST_USER_LOCAL` environment variable for improved test isolation.
Add additional test cases for new set and get claims functions to ensure comprehensive coverage.

fix(firebase.guard): refactor token verification and role handling logic

Improve token verification by abstracting logic into `verifyToken` for cleaner error handling.
Refactor role validation to a dedicated method `handleRoleValidation` to modularize complex
logic and improve maintainability.

miscellaneous:
- Add mock for custom claims to support testing scenarios.
- Update the FirebaseProvider to handle different keys for roles, supporting flexible claim
structures.

Author: Alpha018

.github/workflows/test.yml

@@ -13,6 +13,7 @@ jobs:
         node-version: [ 20.x, 22.x ]
     env:
       FIREBASE_TEST_USER: ${{ secrets.FIREBASE_TEST_USER }}
+      FIREBASE_TEST_USER_LOCAL: ${{ secrets.FIREBASE_TEST_USER_LOCAL }}
       FIREBASE_SERVICE_ACCOUNT_BASE64: ${{ secrets.FIREBASE_SERVICE_ACCOUNT_BASE64 }}
       FIREBASE_CLIENT_BASE64: ${{ secrets.FIREBASE_CLIENT_BASE64 }}
 

README.md

@@ -55,6 +55,7 @@ import { FirebaseAuthGuard } from '@alpha018/nestjs-firebase-auth';
               checkRevoked: true, // Set to true if you want to check for revoked Firebase tokens
               validateRole: true, // Set to true if you want to validate user roles
               useLocalRoles: true, // Set to true if you want to validate user roles locally without firebase call
+              rolesClaimKey: 'user_roles' // Set the name of the key within the Firebase custom claims that stores user roles
             },
           },
         }),
@@ -74,6 +75,7 @@ import { FirebaseAuthGuard } from '@alpha018/nestjs-firebase-auth';
 | `auth.config.checkRevoked`  | `boolean`  | Optional | Set to `true` to check if the Firebase token has been revoked. Defaults to `false`.                                                                                                                                       |
 | `auth.config.validateRole`  | `boolean`  | Optional | Set to `true` to validate user roles using Firebase custom claims. Defaults to `false`.                                                                                                                                   |
 | `auth.config.useLocalRoles` | `boolean`  | Optional | Set to `true` to validate user roles using local custom claims inside the JWT token. Defaults to `false`. **Note:** If you update the claims, previously issued tokens may still contain outdated roles and remain valid. |
+| `auth.config.rolesClaimKey` | `string`   | Optional | The name of the key within the Firebase custom claims that stores user roles. Defaults to `'roles'`. This allows you to customize the property name for roles in your custom claims object.                               |
 
 
 ### Auth Guard Without Role Validation
@@ -96,7 +98,7 @@ export class AppController {
 
 ### Auth Guard With Role Validation
 
-To enforce role-based access control, you need to set custom claims in Firebase. Here's how you can set custom claims:
+To enforce role-based access control, you need to set role-based custom claims in Firebase. Here's how you can set roles for a user using `setClaimsRoleBase`:
 ```ts
 import { FirebaseProvider } from '@alpha018/nestjs-firebase-auth';
 
@@ -106,16 +108,16 @@ enum Roles {
 }
 
 @Controller('')
-export class AppController implements OnModuleInit {
+export class AppController {
   constructor(
     private readonly firebaseProvider: FirebaseProvider,
   ) {}
 
   @Get()
-  async setClaims() {
+  async setUserRoles() {
     await this.firebaseProvider.setClaimsRoleBase<Roles>(
-      'FirebaseUID',
-      [Roles.ADMIN, ...]
+      'some-firebase-uid', // The UID of the user you want to set roles for
+      [Roles.ADMIN]
     );
     return { status: 'ok' }
   }
@@ -213,7 +215,7 @@ export class AppController {
 > **Note:** Starting from version `>=1.7.x`, these two decorators are explicitly separated to avoid confusion (see [issue #11](https://github.com/Alpha018/nestjs-firebase-auth/issues/11)):
 
 - `@FirebaseUser()` → Returns the **full decoded token** (`auth.DecodedIdToken`).
-- `@FirebaseUserClaims()` → Returns only the **custom claims** (roles/permissions) defined for the user.
+- `@FirebaseUserClaims()` → Returns only the **custom role claims** (roles/permissions) defined for the user.
 
 This separation ensures that developers can access both the raw Firebase user object and the role/claims information independently.
 

src/firebase/constant/firebase.constant.ts

@@ -13,3 +13,6 @@ export const FIREBASE_TOKEN_USER_METADATA = 'FIREBASE_USER_METADATA';
 export const FIREBASE_CLAIMS_USER_METADATA = 'FIREBASE_CLAIMS_METADATA';
 /** Metadata key for role based authorization decorator */
 export const FIREBASE_APP_ROLES_DECORATOR = 'ROLES';
+
+export const FIREBASE_APP_ROLES_DEFAULT_DECORATOR = 'roles';
+export const FIREBASE_AUTH_OPTIONS = 'FIREBASE_AUTH_OPTIONS';

src/firebase/decorator/claims.decorator.ts

@@ -18,4 +18,4 @@ export const ClaimsFactory = (data: unknown, ctx: ExecutionContext) => {
 /**
  * Parameter decorator to access a user’s Firebase claims.
  */
-export const FirebaseUserClaims = createParamDecorator(ClaimsFactory);
+export const FirebaseRolesClaims = createParamDecorator(ClaimsFactory);

src/firebase/guard/firebase.guard.ts

@@ -37,64 +37,108 @@ export class FirebaseGuard implements CanActivate {
    * @returns A promise that resolves to `true` if the request is authorized, otherwise `false`.
    */
   async canActivate(context: ExecutionContext): Promise<boolean> {
-    const request = context.switchToHttp().getRequest<Request>();
+    const request = context.switchToHttp().getRequest();
+    const authConfig = this.config.auth?.config;
+
     const token = this.extractTokenFromRequest(request);
 
     if (!token) {
       return false;
     }
 
-    let decodedToken: DecodedIdToken;
-    try {
-      decodedToken = await this.firebaseProvider.auth.verifyIdToken(
-        token,
-        this.config.auth?.config?.checkRevoked || false,
-      );
-    } catch {
+    const decodedToken = await this.verifyToken(token, authConfig?.checkRevoked ?? false);
+    if (!decodedToken) {
       return false;
     }
 
-    request['metadata'] = {
-      ...request['metadata'],
-      [FIREBASE_TOKEN_USER_METADATA]: {
-        user: decodedToken,
-      },
-    };
+    this.attachUserToRequest(request, decodedToken);
 
-    if (!this.config.auth?.config?.validateRole) {
+    if (!authConfig?.validateRole) {
       return true;
     }
 
-    const roles = this.reflector.get(FIREBASE_APP_ROLES_DECORATOR, context.getHandler());
+    return this.handleRoleValidation(
+      context,
+      request,
+      decodedToken,
+      authConfig?.useLocalRoles ?? false,
+    );
+  }
+
+  /**
+   * Handles role-based validation for the request.
+   * It retrieves the roles required by the route handler, fetches the user's roles,
+   * and checks if the user has at least one of the required roles.
+   *
+   * @param context The execution context, used to access route metadata.
+   * @param request The incoming HTTP request object.
+   * @param decodedToken The user's decoded Firebase ID token.
+   * @param useLocalRoles A flag indicating whether to use roles from the token payload or fetch from Firebase.
+   * @returns A promise that resolves to `true` if the user is authorized, otherwise `false`.
+   */
+  private async handleRoleValidation(
+    context: ExecutionContext,
+    request: any,
+    decodedToken: DecodedIdToken,
+    useLocalRoles: boolean,
+  ): Promise<boolean> {
+    const requiredRoles = this.reflector.get(FIREBASE_APP_ROLES_DECORATOR, context.getHandler());
 
-    if (!roles) {
+    if (!requiredRoles) {
       return true;
     }
 
-    const claims = await this.firebaseProvider.getClaimsRoleBase(
-      decodedToken,
-      this.config.auth?.config?.useLocalRoles || false,
-    );
+    const userRoles = await this.firebaseProvider.getClaimsRoleBase(decodedToken, useLocalRoles);
+    this.attachClaimsToRequest(request, userRoles);
+
+    if (!userRoles) {
+      return false;
+    }
 
-    request['metadata'] = {
-      ...request['metadata'],
-      [FIREBASE_CLAIMS_USER_METADATA]: {
-        claims: claims,
-      },
-    };
+    const requiredRolesSet = new Set(requiredRoles);
+    return userRoles.some((role) => requiredRolesSet.has(role));
+  }
 
-    const requiredRoles = new Set(roles);
-    return claims?.some((role) => requiredRoles.has(role));
+  /**
+   * Verifies the Firebase ID token.
+   * @param token The ID token to verify.
+   * @param checkRevoked Whether to check if the token has been revoked.
+   * @returns The decoded token if valid, otherwise `null`.
+   */
+  private async verifyToken(token: string, checkRevoked: boolean): Promise<DecodedIdToken | null> {
+    try {
+      return await this.firebaseProvider.auth.verifyIdToken(token, checkRevoked);
+    } catch {
+      return null;
+    }
   }
 
   /**
    * Extracts a JWT token from the Authorization header.
    * @param request The HTTP request object.
    * @returns The extracted token or `null` if not present.
    */
-  private extractTokenFromRequest(request: Request): string | null {
+  private extractTokenFromRequest(request: any): string | null {
     const extractor =
       this.config.auth?.config?.extractor || ExtractJwt.fromAuthHeaderAsBearerToken();
     return extractor(request);
   }
+
+  /**
+   * Attaches the decoded user token to the request metadata.
+   * @param request The request object.
+   * @param user The decoded Firebase ID token.
+   */
+  private attachUserToRequest(request: any, user: DecodedIdToken): void {
+    request.metadata = { ...request.metadata, [FIREBASE_TOKEN_USER_METADATA]: { user } };
+  }
+
+  /**
+   * Attaches the user's claims to the request metadata.
+   * @param request The request object.
+   * @param claims The user's custom claims.
+   */
+  private attachClaimsToRequest(request: any, claims: unknown): void {
+    request.metadata = { ...request.metadata, [FIREBASE_CLAIMS_USER_METADATA]: { claims } };
+  }
 }

src/firebase/interface/options.interface.ts

@@ -44,4 +44,21 @@ export interface FirebaseAuthStrategyOptions {
    * @default false
    */
   validateRole?: boolean;
+
+  /**
+   * The name of the key within the Firebase custom claims that stores the user's roles.
+   *
+   * This allows you to customize the property name for roles in the custom claims object.
+   * For example, if you set this to `'permissions'`, the library will look for a `permissions`
+   * array in the custom claims.
+   *
+   * All role-related operations performed by `FirebaseProvider` (such as getting, setting, or preserving roles) will use this key.
+   *
+   * @example
+   * // If rolesClaimKey is 'user_roles', the custom claims might look like:
+   * // { "user_roles": ["ADMIN", "EDITOR"] }
+   *
+   * @default 'roles' (defined by `FIREBASE_APP_ROLES_DEFAULT_DECORATOR`)
+   */
+  rolesClaimKey?: string;
 }

src/firebase/provider/firebase.provider.spec.ts

@@ -44,6 +44,11 @@ describe('FirebaseProvider', () => {
         {
           useFactory: () => {
             const data: FirebaseConstructorInterface = {
+              auth: {
+                config: {
+                  rolesClaimKey: 'test',
+                },
+              },
               base64: Buffer.from(JSON.stringify({ project_id: 'test' })).toString('base64'),
             };
             return new FirebaseProvider(data);
@@ -107,44 +112,64 @@ describe('FirebaseProvider', () => {
     });
   });
 
+  describe('setClaimsBase', () => {
+    it('should set custom claims while preserving role claims', async () => {
+      const uid = 'test-uid';
+      const newClaims = { premium: true };
+      const existingRoles = { test: ['user'] };
+      mockAuth.getUser.mockResolvedValue({ customClaims: existingRoles });
+
+      await provider.setClaimsBase(uid, newClaims);
+
+      expect(mockAuth.getUser).toHaveBeenCalledWith(uid);
+      expect(mockAuth.setCustomUserClaims).toHaveBeenCalledWith(uid, {
+        ...newClaims,
+        ...existingRoles,
+      });
+    });
+  });
+
   describe('setClaimsRoleBase', () => {
     it('should set custom user claims', async () => {
       const uid = 'test-uid';
       const claims = ['admin'];
+      mockAuth.getUser.mockResolvedValue({ customClaims: {} });
       mockAuth.setCustomUserClaims.mockResolvedValue(undefined);
 
       await provider.setClaimsRoleBase(uid, claims);
-      expect(mockAuth.setCustomUserClaims).toHaveBeenCalledWith(uid, { roles: claims });
+      expect(mockAuth.setCustomUserClaims).toHaveBeenCalledWith(uid, { test: claims });
     });
   });
 
   describe('getClaimsRoleBase', () => {
-    it('should get custom user claims', async () => {
-      const user = userDecode as any as DecodedIdToken;
+    it('should get claims from local token when localDecode is true', async () => {
       const claims = ['admin'];
-      mockAuth.getUser.mockResolvedValue({
-        customClaims: { roles: claims },
-      });
+      const userWithClaims = { ...userDecode, test: claims } as any as DecodedIdToken;
 
-      const result = await provider.getClaimsRoleBase(user, true);
+      const result = await provider.getClaimsRoleBase(userWithClaims, true);
       expect(result).toEqual(claims);
-
-      const localResult = await provider.getClaimsRoleBase(user, false);
-      expect(localResult).toEqual(claims);
+      expect(mockAuth.getUser).not.toHaveBeenCalled();
     });
 
-    it('should return undefined if no custom claims', async () => {
+    it('should get claims from Firebase when localDecode is false', async () => {
       const user = userDecode as any as DecodedIdToken;
-      user.roles = undefined;
-      mockAuth.getUser.mockResolvedValue({
-        customClaims: undefined,
-      });
+      const claims = ['admin'];
+      mockAuth.getUser.mockResolvedValue({ customClaims: { test: claims } });
 
-      const result = await provider.getClaimsRoleBase(user, true);
-      expect(result).toBeUndefined();
+      const result = await provider.getClaimsRoleBase(user, false);
+      expect(mockAuth.getUser).toHaveBeenCalledWith(user.uid);
+      expect(result).toEqual(claims);
+    });
+
+    it('should return undefined if no custom claims', async () => {
+      const user = { ...userDecode } as any as DecodedIdToken;
+      mockAuth.getUser.mockResolvedValue({ customClaims: null });
 
-      const localResult = await provider.getClaimsRoleBase(user, false);
+      const localResult = await provider.getClaimsRoleBase(user, true);
       expect(localResult).toBeUndefined();
+
+      const remoteResult = await provider.getClaimsRoleBase(user, false);
+      expect(remoteResult).toBeUndefined();
     });
   });
 });

src/firebase/provider/firebase.provider.ts

@@ -5,6 +5,7 @@ import { Injectable } from '@nestjs/common';
 import * as fa from 'firebase-admin';
 
 import { FirebaseConstructorInterface } from '../interface/firebase-constructor.interface';
+import { FIREBASE_APP_ROLES_DEFAULT_DECORATOR } from '../constant/firebase.constant';
 
 @Injectable()
 /**
@@ -62,26 +63,44 @@ export class FirebaseProvider {
    * @returns An array of roles type `T` or `undefined` if no roles are found.
    */
   async getClaimsRoleBase<T>(user: DecodedIdToken, localDecode: boolean): Promise<undefined | T[]> {
+    const rolesKey = this.data.auth.config.rolesClaimKey ?? FIREBASE_APP_ROLES_DEFAULT_DECORATOR;
+
     if (localDecode) {
-      return user.roles;
+      return user?.[rolesKey];
     }
 
     const { customClaims } = await this.auth.getUser(user.uid);
-    return customClaims?.roles;
+    return customClaims?.[rolesKey];
+  }
+
+  /**
+   * Sets custom claims for a specific Firebase user, preserving any existing role claims.
+   * This method merges the new claims with any existing custom claims, but ensures that
+   * the role-specific claim (e.g., 'roles') is not overwritten by this operation.
+   *
+   * @param uid The UID of the user to update.
+   * @param claims An object containing the custom claims to set.
+   * @returns A promise that resolves once the claims are successfully updated.
+   */
+  async setClaimsBase(uid: string, claims: Record<string, any>): Promise<void> {
+    const rolesKey = this.data.auth.config.rolesClaimKey ?? FIREBASE_APP_ROLES_DEFAULT_DECORATOR;
+    const { customClaims } = await this.auth.getUser(uid);
+    return this.auth.setCustomUserClaims(uid, { ...claims, [rolesKey]: customClaims?.[rolesKey] });
   }
 
   /**
-   * Sets role-based claims for a specific Firebase user.
-   * This overwrites the user's custom claims with a new `roles` array.
+   * Sets or overwrites the role-based claims for a specific Firebase user, preserving other custom claims.
+   * This method merges the new role claims with any existing custom claims by overwriting the value
+   * of the role-specific key (e.g., 'roles') while keeping all other claims intact.
    *
-   * @template T The type of roles being assigned.
+   * @template T The type of the elements in the roles array.
    * @param uid The UID of the user to update.
-   * @param claims An array of roles to assign to the user.
+   * @param claims An array of roles to assign to the user. This will replace any existing roles.
    * @returns A promise that resolves once the claims are successfully updated.
    */
-  setClaimsRoleBase<T>(uid: string, claims: T[]): Promise<void> {
-    return this.auth.setCustomUserClaims(uid, {
-      roles: claims,
-    });
+  async setClaimsRoleBase<T>(uid: string, claims: T[]): Promise<void> {
+    const rolesKey = this.data.auth.config.rolesClaimKey ?? FIREBASE_APP_ROLES_DEFAULT_DECORATOR;
+    const { customClaims } = await this.auth.getUser(uid);
+    return this.auth.setCustomUserClaims(uid, { ...(customClaims || {}), [rolesKey]: claims });
   }
 }