@origins-digital/firebase-fan-guard

A NestJS guard package for Firebase authentication of fan users.

Zod compatibility: Environment/config schemas used by this package are compatible with Zod v4.x.

Installation

npm install @origins-digital/firebase-fan-guard

Features

• Firebase token verification for fan authentication
• Optional authentication support
• Automatic public key caching
• Fan payload extraction decorator
• Swagger integration

Usage

Basic Setup

import { Module } from '@nestjs/common';
import { FirebaseFanGuardModule } from '@origins-digital/firebase-fan-guard';

@Module({
  imports: [
    FirebaseFanGuardModule.forRoot({
      publicKeyEndpoint: process.env.FIREBASE_PUBLIC_KEY_ENDPOINT,
    }),
  ],
})
export class AppModule {}

Controller Usage

import { Controller, Get } from '@nestjs/common';
import {
  AuthFirebaseFanGuard,
  FanPayloadParam,
} from '@origins-digital/firebase-fan-guard';
import { DecodedIdToken } from '@origins-digital/firebase-fan-guard';

@Controller('fan')
@AuthFirebaseFanGuard()
export class FanController {
  @Get('profile')
  getProfile(@FanPayloadParam() fanPayload: DecodedIdToken) {
    return {
      email: fanPayload.email,
      name: fanPayload.name,
      // ... other fan data
    };
  }
}

Optional Authentication

import { Controller, Get } from '@nestjs/common';
import {
  OptionalAuthFirebaseFanGuard,
  FanPayloadParam,
} from '@origins-digital/firebase-fan-guard';
import { DecodedIdToken } from '@origins-digital/firebase-fan-guard';

@Controller('fan')
@OptionalAuthFirebaseFanGuard()
export class FanController {
  @Get('profile')
  getProfile(@FanPayloadParam() fanPayload?: DecodedIdToken) {
    if (fanPayload) {
      return {
        email: fanPayload.email,
        name: fanPayload.name,
        // ... authenticated fan data
      };
    }
    return {
      // ... public fan data
    };
  }
}

Swagger Integration

import { Controller, Get } from '@nestjs/common';
import {
  ApiAuthFirebaseFanGuard,
  FanPayloadParam,
} from '@origins-digital/firebase-fan-guard';
import { DecodedIdToken } from '@origins-digital/firebase-fan-guard';

@Controller('fan')
@ApiAuthFirebaseFanGuard()
export class FanController {
  @Get('profile')
  getProfile(@FanPayloadParam() fanPayload: DecodedIdToken) {
    return {
      email: fanPayload.email,
      name: fanPayload.name,
    };
  }
}

Error Handling

The guard will throw the following exceptions:

• BadRequestException: When client configuration is missing or email is not verified
• UnauthorizedException: When token is missing or invalid

Configuration

The FirebaseFanGuardModule accepts the following configuration:

interface FirebaseFanGuardConfig {
  publicKeyEndpoint: string;
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.