appsec-ui

AppSec UI Library

A plug-and-play RBAC (Role-Based Access Control) dashboard UI library for React/Next.js applications.

Features

• RBAC Management: Complete user interface for managing roles, permissions, and access control
• Onboarding Flow: Step-by-step setup wizard for configuring RBAC systems
• API Caching: Built-in TanStack Query integration for efficient API response caching
• Modern UI: Built with Tailwind CSS and Lucide React icons
• TypeScript: Full TypeScript support with comprehensive type definitions

Installation

npm install appsec-ui

Quick Start

1. Set up providers

Wrap your application with the required providers:

import { RbacQueryProvider, AppsecProvider } from 'appsec-ui';

function App() {
  return (
    <RbacQueryProvider>
      <AppsecProvider
        appId="your-app-id"
        baseUrl="https://your-api-endpoint.com/api"
        appsecUrl="https://your-appsec-endpoint.com"
        mode="manage"
        getAuthToken={() => localStorage.getItem('authToken')}
      >
        {/* Your app content */}
      </AppsecProvider>
    </RbacQueryProvider>
  );
}

2. Use RBAC Management Component

import { RBACManagement } from 'appsec-ui';

function MyApp() {
  return (
    <div className="container mx-auto p-4">
      <RBACManagement />
    </div>
  );
}

TanStack Query Integration

This library uses TanStack Query (React Query) for efficient API caching and state management. The integration provides:

Automatic Caching

• API responses are automatically cached for 5 minutes
• Prevents unnecessary API calls on component re-renders
• Background refetching keeps data fresh

Query Keys

The library uses structured query keys for cache management:

• ['rbac', 'app', appId] - App information
• ['rbac', 'modules', appMongoId] - Application modules
• ['rbac', 'roles', appMongoId] - User roles
• ['rbac', 'acls', appMongoId] - Access control lists
• ['rbac', 'groups', appMongoId] - User groups

Mutation Handling

Mutations automatically invalidate related queries:

• Creating/updating ACLs invalidates ACL queries
• Bulk operations update the cache optimistically

Configuration

You can customize the query client behavior:

import { queryClient } from 'appsec-ui';

// Customize default options
queryClient.setDefaultOptions({
  queries: {
    staleTime: 10 * 60 * 1000, // 10 minutes
    retry: 1,
  },
});

API Requirements

Your backend API should provide the following endpoints:

• GET /apps?name={appId} - Get app information
• GET /modules?appId={appId} - Get application modules
• GET /roles?appId={appId} - Get user roles
• GET /acl?application={appId} - Get access control entries
• GET /groups?appId={appId} - Get user groups
• POST /acl - Create access control entry
• DELETE /acl?_id={id} - Delete access control entry
• PUT /acl/bulkUpdate - Bulk update access control entries

Components

RBACManagement

Main component for managing RBAC configuration.

<RBACManagement
  defaultTab="groups"
  className="custom-styles"
/>

OnboardingStepper

Step-by-step onboarding flow for setting up RBAC.

<OnboardingStepper
  onComplete={() => console.log('Onboarding complete')}
/>

Styling

This library uses Tailwind CSS with custom CSS variables for theming. Make sure to include Tailwind in your project:

npm install -D tailwindcss

The library uses these CSS custom properties:

• --appsec-bg - Background color
• --appsec-surface - Surface/card color
• --appsec-border - Border color
• --appsec-text - Primary text color
• --appsec-text-secondary - Secondary text color

TypeScript Support

The library is written in TypeScript and provides comprehensive type definitions. All components and hooks are fully typed.

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

License

MIT

Per-mode PIN components

The PIN flow consists of three independently importable components. Enrollment verifies the emailed six-digit OTP, then creates a six-digit PIN with one server-provided recovery answer. Normal access uses the PIN keypad. Recovery verifies the emailed recovery OTP and registered answer before allowing the PIN to be reset.

import { EnterModePin, ResetModePin, SetupModePin } from "appsec-ui";

<SetupModePin
  modeId={modeId}
  email={currentUser.email}
  appsecUrl="https://appsec.example.com"
  credentials="include"
  onSuccess={() => showModeLogin()}
/>

<EnterModePin
  modeId={modeId}
  appsecUrl="https://appsec.example.com"
  credentials="include"
  onSuccess={() => enterMode()}
  // Called only after /api/mode-pin/forgot confirms the recovery OTP was sent.
  onForgotPin={({ sent }) => {
    if (sent) setScreen("reset");
  }}
/>

<ResetModePin
  modeId={modeId}
  appsecUrl="https://appsec.example.com"
  credentials="include"
  securityQuestion={forgotResultQuestion}
  onSuccess={() => setScreen("enter")}
/>

Requests include cookies by default. For bearer authentication, pass authToken as a string or a function that returns the latest token. A custom request transport can also be supplied. Each component accepts exactly one of modeId, modeName, appId, or appName. Styling uses the same Tailwind theme tokens as the rest of the library.