Package Exports

exguard-backend

Readme

ExGuard Backend SDK v2.0

🛡️ Enterprise-grade RBAC backend protection with intelligent caching and realtime support.

A powerful backend SDK for protecting API endpoints with role-based access control, featuring smart caching and automatic realtime invalidation.

🚀 Features

🔒 Endpoint Protection - Protect API endpoints with permissions, roles, and modules
⚡ Smart Caching - 95%+ performance improvement with intelligent caching
🔄 Realtime Updates - Automatic cache invalidation on RBAC changes
🌐 Framework Support - Express, Fastify, NestJS, and framework-agnostic
📊 Performance Monitoring - Cache statistics and optimization
🔧 Easy Integration - Drop-in middleware and guard implementations

📦 Installation

npm install @your-org/exguard-backend
# or
yarn add @your-org/exguard-backend
# or
pnpm add @your-org/exguard-backend

🚀 Quick Start

Express.js Protection

import express from 'express';
import { createExGuardExpress } from '@your-org/exguard-backend';

const app = express();
const exGuard = createExGuardExpress({
  apiUrl: 'http://localhost:3000',
  cache: { enabled: true, ttl: 300000 }, // 5 minutes cache
});

// Protect endpoints with permissions
app.get('/api/events', 
  exGuard.requirePermissions(['events:read']), 
  async (req, res) => {
    const events = await getEvents();
    res.json({ success: true, data: events });
  }
);

app.listen(3001);

Fastify Protection

import fastify from 'fastify';
import { createExGuardFastify } from '@your-org/exguard-backend';

const app = fastify();
const exGuard = createExGuardFastify({
  apiUrl: 'http://localhost:3000',
  cache: { enabled: true },
});

app.get('/api/events', {
  preHandler: exGuard.requirePermissions(['events:read'])
}, async (request, reply) => {
  const events = await getEvents();
  return { success: true, data: events };
});

Framework-Agnostic Usage

import { Guard } from '@your-org/exguard-backend/guards';

const guard = new Guard({
  apiUrl: 'http://localhost:3000',
  cache: { enabled: true, ttl: 300000 },
});

// Check permissions
const result = await guard.requirePermissions(
  { token: 'jwt-token' }, 
  ['events:read']
);

if (result.allowed) {
  console.log('Access granted:', result.user);
} else {
  console.log('Access denied:', result.error);
}

📚 Documentation

Backend Protection Guide - Complete usage guide
Integration & Publishing - Setup, integration, and publishing instructions
Enhanced Features - Caching and realtime features

🛠️ Setup & Integration

Quick Setup

# Clone and setup
git clone https://github.com/your-org/exguard-backend.git
cd exguard-backend
node setup.js

# Install dependencies
npm install

# Build and test
npm run build
npm test

Framework Integrations

Framework	Integration	Performance
Express.js	Middleware	✅ Optimized
Fastify	Plugin/Hooks	✅ Optimized
NestJS	Guards	✅ Optimized
Generic Node.js	Direct API	✅ Optimized

📊 Performance

Operation	Without Cache	With Cache	Improvement
Single Permission Check	~100ms	~5ms	95% faster
10 Permission Checks	~1000ms	~10ms	99% faster
100 Concurrent Requests	~10s	~0.5s	95% faster

🔧 Configuration

const exGuard = createExGuardExpress({
  apiUrl: 'http://localhost:3000',
  timeout: 10000,
  
  cache: {
    enabled: true,        // Enable caching
    ttl: 300000,         // 5 minutes TTL
  },
  
  realtime: {
    enabled: true,                    // Enable realtime
    url: 'ws://localhost:3000/realtime', // WebSocket URL
    token: 'service-jwt-token',           // Service JWT token
  },
});

🚀 Publishing

# Update version
npm version patch  # 2.0.0 -> 2.0.1

# Build and test
npm run build
npm test

# Publish
npm publish

# Or publish beta
npm run publish:beta

See Integration Guide for complete publishing instructions.

🎯 Use Cases

Admin Panel Protection

app.get('/api/admin/users', 
  exGuard.requireRoles(['Admin']), 
  getUsersHandler
);

Multi-tenant Applications

app.get('/api/field-offices/:office/data', 
  exGuard.requireFieldOffices(['FO-MANILA', 'FO-CEBU']), 
  getOfficeDataHandler
);

Complex Requirements

app.post('/api/sensitive',
  exGuard.require({
    permissions: ['sensitive:execute'],
    roles: ['Manager'],
    modules: ['operations'],
    requireAll: true
  }), 
  handler
);

🔄 Migration from v1.x

// v1.x (old)
import { ExGuardBackend } from 'exguard-backend';
const guard = new ExGuardBackend({ apiUrl: 'http://localhost:3000' });

// v2.x (new)
import { createExGuardExpress } from '@your-org/exguard-backend';
const exGuard = createExGuardExpress({ 
  apiUrl: 'http://localhost:3000',
  cache: { enabled: true }, // New: caching
});

API Reference

Constructor

new ExGuardBackend(config: ExGuardConfig)

Config:

apiUrl (string): Base URL of your Guard API
timeout (number, optional): Request timeout in milliseconds (default: 10000)

Methods

`getUserAccess(token: string): Promise<UserAccessResponse>`

Get complete user access information including roles, permissions, and field offices.

Returns:

{
  user: User,
  groups: string[],
  roles: string[],
  module: string[],
  modules: ModulePermission[],
  fieldOffices: string[]
}

`hasPermission(token: string, permission: string): Promise<boolean>`

Check if user has a specific permission.

Example:

const canCreateEvent = await exGuard.hasPermission(token, 'events:create');

`hasRole(token: string, role: string): Promise<boolean>`

Check if user has a specific role.

Example:

const isEventManager = await exGuard.hasRole(token, 'Event Manager');

`getModulePermissions(token: string, moduleKey: string): Promise<string[]>`

Get all permissions for a specific module.

Example:

const eventPermissions = await exGuard.getModulePermissions(token, 'events');
// Returns: ['events:create', 'events:read', 'events:update', 'events:delete']

`getUserRoles(token: string): Promise<string[]>`

Get all user roles.

Example:

const roles = await exGuard.getUserRoles(token);
// Returns: ['Event Manager', 'Viewer']

`getUserFieldOffices(token: string): Promise<string[]>`

Get all user field offices.

Example:

const fieldOffices = await exGuard.getUserFieldOffices(token);
// Returns: ['FO-MIMAROPA', 'FO-NCR']

Usage Examples

Express.js Middleware

import express from 'express';
import { ExGuardBackend } from 'exguard-backend';

const app = express();
const exGuard = new ExGuardBackend({
  apiUrl: process.env.GUARD_API_URL || 'http://localhost:3001'
});

// Middleware to check permissions
const requirePermission = (permission: string) => {
  return async (req: express.Request, res: express.Response, next: express.NextFunction) => {
    const token = req.headers.authorization?.replace('Bearer ', '');
    
    if (!token) {
      return res.status(401).json({ error: 'No token provided' });
    }

    try {
      const hasPermission = await exGuard.hasPermission(token, permission);
      if (!hasPermission) {
        return res.status(403).json({ error: 'Insufficient permissions' });
      }
      next();
    } catch (error) {
      return res.status(401).json({ error: 'Invalid token' });
    }
  };
};

// Use in routes
app.post('/events', requirePermission('events:create'), (req, res) => {
  // Your route logic here
});

NestJS Guard

import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { ExGuardBackend } from 'exguard-backend';

@Injectable()
export class PermissionGuard implements CanActivate {
  private exGuard = new ExGuardBackend({
    apiUrl: process.env.GUARD_API_URL
  });

  constructor(private requiredPermission: string) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const token = request.headers.authorization?.replace('Bearer ', '');
    
    if (!token) {
      return false;
    }

    return await this.exGuard.hasPermission(token, this.requiredPermission);
  }
}

// Usage in controller
@Get('events')
@UseGuards(new PermissionGuard('events:read'))
async getEvents() {
  // Your logic here
}

Error Handling

The SDK throws specific errors for different scenarios:

Unauthorized: Invalid or expired token (401)
API Error: General API errors with detailed messages
Network Error: Connection issues

Always wrap SDK calls in try-catch blocks for proper error handling.

License

MIT