Bug: FirebaseUser decorator returns nested user object instead of direct DecodedIdToken

[xandru314]

Description

When using the @FirebaseUser() decorator in version 1.6.0, the returned user object is nested within another user property, causing the structure to be { user: DecodedIdToken } instead of the expected DecodedIdToken directly.

Environment

• Package version: @alpha018/nestjs-firebase-auth@1.6.0
• Firebase Admin SDK: firebase-admin@13.35.1
• Node.js version: 20.x
• NestJS version: Latest
• Environment: Firebase Emulator Suite (Auth Emulator)

Expected Behavior

The @FirebaseUser() decorator should return the Firebase DecodedIdToken directly:

@UseGuards(FirebaseGuard)
@Get('protected')
getProtectedRoute(@FirebaseUser() user: auth.DecodedIdToken) {
  console.log(user.uid); // Should work directly
  return { user };
}

Expected response:

{
  "user": {
    "uid": "user123",
    "email": "user@example.com",
    "iat": 1234567890,
    // ... other DecodedIdToken properties
  }
}

Actual Behavior

The decorator returns a nested object structure:

@UseGuards(FirebaseGuard)
@Get('protected')
getProtectedRoute(@FirebaseUser() user: any) {
  console.log(user.user.uid); // Have to access nested property
  return { user };
}

Actual response:

{
  "user": {
    "user": {
      "uid": "user123",
      "email": "user@example.com",
      "iat": 1234567890,
      // ... other DecodedIdToken properties
    }
  }
}

Steps to Reproduce

1. Set up NestJS project with Firebase Emulator Suite
2. Configure @alpha018/nestjs-firebase-auth@1.6.0 with the following config:

FirebaseAdminModule.forRootAsync({
  imports: [ConfigModule],
  useFactory: (configService: ConfigService) => {
    const isEmulator = configService.get('NODE_ENV') === 'development';

    if (isEmulator) {
      process.env.FIREBASE_AUTH_EMULATOR_HOST = 'localhost:9099';
      process.env.FIRESTORE_EMULATOR_HOST = 'localhost:8080';
      process.env.FIREBASE_STORAGE_EMULATOR_HOST = 'localhost:9199';
    }

    return {
      options: {
        projectId: configService.get('FIREBASE_PROJECT_ID') || 'demo-project',
      },
      auth: {
        config: {
          extractor: ExtractJwt.fromAuthHeaderAsBearerToken(),
          checkRevoked: false,
          validateRole: false,
          useLocalRoles: false,
        },
      },
    };
  },
  inject: [ConfigService],
}),

3. Create a protected endpoint:

@UseGuards(FirebaseGuard)
@Get('protected')
getProtectedRoute(@FirebaseUser() user: auth.DecodedIdToken) {
  return { user };
}

4. Start Firebase emulators: firebase emulators:start
5. Make authenticated request to the endpoint
6. Observe the nested user structure in the response

Root Cause Analysis

Looking at the source code in src/firebase/decorator/user.decorator.ts, the decorator extracts user data from request.metadata[FIREBASE_TOKEN_USER_METADATA]. The issue appears to be that somewhere in the authentication pipeline (likely in the guard or strategy), the user data is being stored as:

request.metadata[FIREBASE_TOKEN_USER_METADATA] = {
  user: decodedToken,
  // possibly other properties
};

Instead of:

request.metadata[FIREBASE_TOKEN_USER_METADATA] = decodedToken;

Workaround

Currently using a monkey patch to fix the issue:

// firebase-user.decorator.patch.ts
import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const UserFactory = (data: unknown, ctx: ExecutionContext) => {
  const context = ctx.switchToHttp();
  const request = context.getRequest();
  let user = request.metadata?.firebase_user; // or whatever the constant is
  
  // Fix nested user issue
  if (user && user.user && typeof user.user === 'object') {
    user = user.user;
  }
  
  return user;
};

export const FirebaseUser = createParamDecorator(UserFactory);

Possible Fix

The issue likely needs to be fixed in the guard or strategy where the user data is stored in the request metadata. The code should store the DecodedIdToken directly rather than wrapping it in an additional object.

Additional Context

• This issue might be specific to Firebase Emulator usage
• The issue was not present in earlier versions (needs verification)
• TypeScript expects auth.DecodedIdToken but receives { user: auth.DecodedIdToken }

Is this related to Firebase Emulator?

This might be emulator-specific behavior. Could you confirm if this also happens in production Firebase environments?

Thanks for this excellent library! This is likely a simple fix but causes confusion for developers expecting the documented behavior.

[Alpha018]

I understand your point and I agree @xandru314 👍.

On the other hand, note that within the @FirebaseUser decorator, there is also a "claim" parameter, which represents the custom claims that can be integrated into the user. That’s why the object has both "user" and "claims".

Because of that, one possible approach would be to provide two decorators: one for the user and another for the claims. This would also need to be reflected in the documentation.

If you like the idea, I could integrate it during the week — it’s a small change anyway. In the meantime, what do you think about leaving it as two separate decorators?

[xandru314]

Again. Thank you very much for the quick response @Alpha018 ! I think two decorators would be a wonderful solution if possible. But it would be also enough to just return the excpected type DecodedIdToken .In your docu you show @FirebaseUser() user auth.DecodedIdToken, which suggest that the user is of that type. The reality is however that it returns a nested DecodedIdToken wrapped in a parent "user" object. That causes confusion because it returns a type you haven't excpected and isn't documented anywhere.

[Alpha018]

Thanks for bringing up this point 🙌

The changes requested in this issue have already been addressed in PR #14.

From version >=1.7.x, the decorators are now clearly separated to avoid confusion:

• @FirebaseUser() → returns the full decoded token (auth.DecodedIdToken)
• @FirebaseUserClaims() → returns only the custom claims (roles/permissions)

This separation ensures a more explicit and predictable usage. 🚀

If possible, it would be great if you could also help test the latest release in your environment, to validate the behavior in addition to the existing unit and e2e tests. Your feedback will help confirm that everything works as expected. ✅

[xandru314]

@firebaseuser() user works now perfectly and as expected! Thank you very much for that! Regarding @FirebaseUserClaims() I think you shouldn't force devs to use your predefined Roles (I think currently it is looking for the "ROLES" claim). The claims could be whatever not only Roles. I would make it more open and just return the claims themselves OR make the claim it's looking for configurable. We for example are currently migrating from firebase functions to nestjs but our role claim is "role" and not "ROLES". We would need to change that for every single user we have which is not feasible. So maybe let @FirebaseUserClaims() return just all claims and the dev can cast it in the end to whatever type he already has and make the claim that @RolesGuard is looking for configurable.

[Alpha018]

@xandru314 Let me see if I understand correctly: is the issue that the @FirebaseUserClaims() decorator currently only returns the enum of roles (e.g. ROLES) and not all the user claims?

If that's the case, one way to address it could be to separate responsibilities:

• Keep a specific decorator like @FirebaseRolesClaims() that only returns the user’s roles array.
• And make @FirebaseUserClaims() return the full claims object, so each developer can use or map it according to their needs.

Would this approach make sense to you?

[xandru314]

@Alpha018 Yes that sounds great! But pls make the @FirebaseRolesClaims configurable somehow so the array it's looking for can be adjusted.

[Alpha018]

@xandru314 Just to be clear, could you give me an example of how you would expect the decorator to behave?

[xandru314]

So we should have a possibility to set the name of the role array it's looking for. Something like FirebaseAuth.init(authKey: "ROLES") in our app.module or bootstrap() in main.ts. I would prefer in app.module if possible. By default it can scan for the key you already have. @FirebaseRolesClaims() then simply returns an array of the claims. The RoleGuard would also take the configurable authKey and scan for that instead of the hardcoded "ROLES" key there is right now. Is that understandable?