Decorators

Authentication decorators for protecting endpoints and accessing user data

The Auth module provides decorators that integrate seamlessly with Vercube controllers, making it easy to protect endpoints and access authenticated user data.

@Auth

The @Auth decorator protects controller methods by requiring authentication before execution. It invokes the registered AuthProvider.validate() method to verify the request.

Basic Usage

import { Controller, Get, Post } from '@vercube/core';
import { Auth } from '@vercube/auth';

@Controller('/api')
export class ApiController {
  
  @Get('/public')
  public publicEndpoint() {
    return { message: 'Anyone can access this' };
  }
  
  @Get('/protected')
  @Auth()
  public protectedEndpoint() {
    return { message: 'Only authenticated users can access this' };
  }
}

Role-Based Protection

Pass options to restrict access based on user roles:

import { Controller, Get, Delete } from '@vercube/core';
import { Auth, User } from '@vercube/auth';

@Controller('/admin')
export class AdminController {
  
  @Get('/dashboard')
  @Auth({ roles: ['admin'] })
  public getDashboard() {
    return { dashboard: 'admin data' };
  }
  
  @Delete('/users/:id')
  @Auth({ roles: ['admin', 'superadmin'] })
  public deleteUser() {
    // Only admins and superadmins can delete users
  }
}

Options

OptionTypeDescription
rolesstring[]Array of roles allowed to access the endpoint

The options are passed to your AuthProvider.validate() method as the second parameter.

@User

The @User decorator injects the currently authenticated user into a controller method parameter. It calls the registered AuthProvider.getCurrentUser() method to retrieve the user.

Basic Usage

import { Controller, Get } from '@vercube/core';
import { Auth, User } from '@vercube/auth';

interface User {
  id: number;
  username: string;
  email: string;
}

@Controller('/profile')
export class ProfileController {
  
  @Get('/')
  @Auth()
  public getProfile(@User() user: User) {
    return {
      id: user.id,
      username: user.username,
      email: user.email
    };
  }
}

Custom Auth Provider

You can specify a custom auth provider for the @User decorator:

import { Controller, Get } from '@vercube/core';
import { User } from '@vercube/auth';
import { CustomAuthProvider } from '../providers/CustomAuthProvider';

@Controller('/api')
export class ApiController {
  
  @Get('/me')
  public getMe(@User({ provider: CustomAuthProvider }) user: CustomUser) {
    return user;
  }
}

Options

OptionTypeDescription
providertypeof AuthProviderCustom auth provider class to use

Combining Decorators

Use @Auth and @User together to protect endpoints and access user data:

import { Controller, Get, Post, Put } from '@vercube/core';
import { Auth, User } from '@vercube/auth';

interface User {
  id: number;
  username: string;
  roles: string[];
}

@Controller('/users')
export class UserController {
  
  @Get('/me')
  @Auth()
  public getCurrentUser(@User() user: User) {
    return user;
  }
  
  @Put('/me')
  @Auth()
  public updateProfile(@User() user: User) {
    // Update user profile
    return { updated: true, userId: user.id };
  }
  
  @Get('/all')
  @Auth({ roles: ['admin'] })
  public getAllUsers(@User() admin: User) {
    // Admin can view all users
    return { requestedBy: admin.username, users: [] };
  }
  
  @Post('/ban/:id')
  @Auth({ roles: ['admin', 'moderator'] })
  public banUser(@User() moderator: User) {
    // Admins and moderators can ban users
    return { bannedBy: moderator.username };
  }
}
Report an issue or Edit this page on GitHub
Previous

API Reference

Complete API reference for the Vercube Auth module

Next