🛡️ Fire Shield - Next.js Adapter

Next.js integration for Fire Shield RBAC authorization.

Installation

pnpm add @fire-shield/[email protected] @fire-shield/[email protected]

Quick Start

App Router (Next.js 13+)

// lib/rbac.ts
import { RBAC } from '@fire-shield/core';
import { NextRBACAdapter } from '@fire-shield/next';
import { getUser } from './auth';

export const rbac = new RBAC();

rbac.createRole('admin', ['user:*', 'post:*']);
rbac.createRole('editor', ['post:read', 'post:write']);

export const rbacAdapter = new NextRBACAdapter(rbac, {
  getUser: (req) => getUser(req),
});

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { rbacAdapter } from './lib/rbac';

const adminMiddleware = rbacAdapter.middleware('admin:access');

export async function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/admin')) {
    const response = await adminMiddleware(request);
    if (response) return response; // returns 403 if unauthorized
  }

  return NextResponse.next();
}

export const config = {
  matcher: '/admin/:path*',
};

API Routes

// app/api/admin/users/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { rbacAdapter } from '@/lib/rbac';
import { getUsers } from '@/lib/users';

export const GET = rbacAdapter.withPermission(
  'user:read',
  async (request: NextRequest) => {
    const users = await getUsers();
    return NextResponse.json({ users });
  }
);

Server Components

// app/admin/page.tsx
import { rbac } from '@/lib/rbac';
import { getUser } from '@/lib/auth';
import { redirect } from 'next/navigation';

export default async function AdminPage() {
  const user = await getUser();

  if (!rbac.hasPermission(user, 'admin:access')) {
    redirect('/unauthorized');
  }

  return (
    <div>
      <h1>Admin Dashboard</h1>
    </div>
  );
}

Pages Router (Next.js 12)

// pages/api/admin/users.ts
import { rbacAdapter } from '@/lib/rbac';

export default rbacAdapter.withPermissionPagesRouter(
  'user:read',
  async (req, res) => {
    const users = await getUsers();
    res.json({ users });
  }
);

API

new NextRBACAdapter(rbac, options?)

Creates a new Next.js adapter instance.

Options:

• getUser?: (req) => RBACUser | Promise<RBACUser> - Extract user from request
• onUnauthorized?: (result, req, res) => void - Custom unauthorized handler
• onError?: (error, req, res) => void - Custom error handler

Methods

adapter.withPermission(permission, handler)

HOC for App Router route handlers. Wraps a handler with a permission check.

import { rbacAdapter } from '@/lib/rbac';

export const GET = rbacAdapter.withPermission('user:read', async (req) => {
  const users = await getUsers();
  return NextResponse.json({ users });
});

adapter.withRole(role, handler)

HOC for App Router route handlers with role check.

import { rbacAdapter } from '@/lib/rbac';

export const GET = rbacAdapter.withRole('admin', async (req) => {
  const stats = await getAdminStats();
  return NextResponse.json({ stats });
});

adapter.withPermissionPagesRouter(permission, handler)

HOC for Pages Router API routes with permission check.

adapter.withRolePagesRouter(role, handler)

HOC for Pages Router API routes with role check.

adapter.middleware(permission)

Returns an async function for use in middleware.ts. Returns a Response on failure, or undefined to allow the request through.

adapter.requirePermission(user, permission)

Throws an error if the user lacks the permission. Use in Server Actions.

adapter.requireRole(user, role)

Throws an error if the user lacks the role. Use in Server Actions.

Examples

Middleware Protection

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { rbac } from './lib/rbac';

const protectedRoutes = {
  '/admin': 'admin:access',
  '/api/users': 'user:read',
  '/api/posts': 'post:read',
};

export function middleware(request: NextRequest) {
  const pathname = request.nextUrl.pathname;
  const user = getUserFromRequest(request);

  // Find matching protected route
  for (const [route, permission] of Object.entries(protectedRoutes)) {
    if (pathname.startsWith(route)) {
      if (!rbac.hasPermission(user, permission)) {
        return NextResponse.json(
          { error: 'Forbidden' },
          { status: 403 }
        );
      }
    }
  }

  return NextResponse.next();
}

Server Actions (Next.js 13+)

'use server';

import { rbac } from '@/lib/rbac';
import { getUser } from '@/lib/auth';
import { revalidatePath } from 'next/cache';

export async function deleteUser(userId: string) {
  const user = await getUser();

  // Check permission
  if (!rbac.hasPermission(user, 'user:delete')) {
    throw new Error('Forbidden: Missing user:delete permission');
  }

  await db.users.delete(userId);
  revalidatePath('/admin/users');

  return { success: true };
}

Client Component Protection

// components/AdminButton.tsx
'use client';

import { useUser } from '@/hooks/useUser';
import { rbac } from '@/lib/rbac';

export function AdminButton() {
  const user = useUser();

  if (!rbac.hasPermission(user, 'admin:access')) {
    return null; // Hide button
  }

  return (
    <button onClick={handleAdminAction}>
      Admin Action
    </button>
  );
}

Audit Logging with Next.js

import { RBAC, BufferedAuditLogger } from '@fire-shield/core';
import { db } from '@/lib/database';

const auditLogger = new BufferedAuditLogger(
  async (events) => {
    await db.auditLogs.insertMany(events.map(e => ({
      ...e,
      createdAt: new Date(e.timestamp)
    })));
  },
  { maxBufferSize: 100, flushIntervalMs: 5000 }
);

export const rbac = new RBAC({ auditLogger });

License

DIB © Fire Shield Team

Links

• Fire Shield Core
• Next.js Documentation
• NPM