managarten/packages/shared-nestjs-auth/README.md

@manacore/shared-nestjs-auth

Shared authentication utilities for NestJS backends in the Mana Core ecosystem.

Installation

pnpm add @manacore/shared-nestjs-auth

Usage

1. Configure Environment Variables

# Required: Mana Core Auth service URL
MANA_CORE_AUTH_URL=http://localhost:3001

# Optional: Development mode auth bypass
NODE_ENV=development
DEV_BYPASS_AUTH=true
DEV_USER_ID=your-test-user-id

2. Use in Controllers

import { Controller, Get, UseGuards } from '@nestjs/common';
import { JwtAuthGuard, CurrentUser, CurrentUserData } from '@manacore/shared-nestjs-auth';

@Controller('api')
export class MyController {
  // Public endpoint
  @Get('health')
  health() {
    return { status: 'ok' };
  }

  // Protected endpoint
  @Get('profile')
  @UseGuards(JwtAuthGuard)
  getProfile(@CurrentUser() user: CurrentUserData) {
    return {
      userId: user.userId,
      email: user.email,
      role: user.role,
    };
  }
}

3. Apply Guard Globally (Optional)

// app.module.ts
import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
import { JwtAuthGuard } from '@manacore/shared-nestjs-auth';

@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: JwtAuthGuard,
    },
  ],
})
export class AppModule {}

API

JwtAuthGuard

A NestJS guard that validates JWT tokens via the Mana Core Auth service.

• Extracts Bearer token from Authorization header
• Calls POST /api/v1/auth/validate on auth service
• Attaches user data to request object
• Supports DEV_BYPASS_AUTH=true for development

CurrentUser Decorator

Parameter decorator to extract the authenticated user from the request.

@Get('me')
@UseGuards(JwtAuthGuard)
getMe(@CurrentUser() user: CurrentUserData) {
  return user;
}

CurrentUserData Interface

interface CurrentUserData {
  userId: string;      // User ID (from JWT sub claim)
  email: string;       // User email
  role: string;        // User role (user, admin, service)
  sessionId?: string;  // Session ID (optional)
}

How It Works

1. Client sends request with Authorization: Bearer <token> header
2. JwtAuthGuard extracts the token
3. Guard calls Mana Core Auth service to validate token
4. On success, user data is attached to request.user
5. Controller receives user via @CurrentUser() decorator

┌─────────────┐     ┌─────────────┐     ┌────────────────┐
│   Client    │────>│  Your API   │────>│ mana-core-auth │
│             │     │  (NestJS)   │     │   (port 3001)  │
└─────────────┘     └─────────────┘     └────────────────┘
      │                   │                     │
      │ Bearer token      │ POST /validate      │
      │                   │ {token}             │
      │                   │<────────────────────│
      │                   │ {valid, payload}    │
      │<──────────────────│                     │
      │ Response          │                     │

Development Mode

Set DEV_BYPASS_AUTH=true in development to skip token validation:

NODE_ENV=development
DEV_BYPASS_AUTH=true
DEV_USER_ID=17cb0be7-058a-4964-9e18-1fe7055fd014

This will use a mock user for all authenticated requests.

Related Packages

• @manacore/shared-auth - Client-side auth for web/mobile apps
• @manacore/shared-types - Shared TypeScript types