Auth & RBAC Utilities

A comprehensive reference of functions and hooks to check user roles and permissions across different contexts.

Overview

JopiJS provides a set of utility functions to check user roles and manage sessions. These tools are available in three main contexts: React Components, API Routes, and Module Initialization.

1. React Context (Hooks & Components)

These tools are part of the core UI logic and work seamlessly in both the browser and during SSR. They are typically exported via the virtual @/ paths.

Hooks

Hook	Purpose
`useGetInfos`	Returns the current user's profile (IUserInfos).
`useHasAllRoles`	Returns `true` if the user has all specified roles.
`useHasOneOfThisRoles`	Returns `true` if the user has at least one of the specified roles.
`useLogOut`	Returns a function to terminate the current session.

src/mod_ui/UserProfile.tsx

import useGetInfos from "@/hooks/jopijs.user.useGetInfos";
import useHasOneOfThisRoles from "@/hooks/jopijs.user.useHasOneOfThisRoles";

export default function UserProfile() {
    const user = useGetInfos();
    const isAdmin = useHasOneOfThisRoles(["admin"]);

    if (!user) return <p>Please log in.</p>;

    return (
        <div>
            <p>Welcome, {user.fullName} {isAdmin && "(Administrator)"}</p>
        </div>
    );
}

Components

<CheckRoles roles={["role1"]}>: A wrapper that only renders its children if the user matches the required roles.

src/mod_ui/AdminPanel.tsx

import CheckRoles from "@/ui/jopijs.user.CheckRoles";

export default function AdminPanel() {
    return (
        <div>
            <h1>Dashboard</h1>
            
            <CheckRoles roles={["admin", "manager"]}>
                <button>Delete User</button>
            </CheckRoles>
        </div>
    );
}

2. API Context (`JopiRequest`)

When writing backend logic (e.g., onPOST.ts, onGET.ts), you can access role-checking methods directly from the JopiRequest object.

src/mod_api/onPOST.ts

import { JopiRequest } from "jopijs";

export default function(req: JopiRequest) {
    // 1. Get raw roles
    const roles = req.role_getUserRoles();
    
    // 2. Boolean check (non-blocking)
    const canWrite = req.role_userHasOneOfThisRoles(["editor", "admin"]);
    
    // 3. Assertion (blocking)
    // Throws a 401 error automatically if conditions are not met.
    req.role_assertUserHasOneOfThisRoles(["admin"]);

    return { success: true };
}

3. Module Initialization (`uiInit.tsx`)

In your module's entry point, you can perform checks before the application fully boots.

src/mod_my_feature/uiInit.tsx

import { JopiUiApplication } from "jopijs/ui";

export default function(uiApp: JopiUiApplication) {
    // Execute logic only if the user matches roles
    uiApp.ifUserHasOneOfThisRoles(["beta_tester", "admin"], (userInfos) => {
        console.log("Initializing premium features for", userInfos.fullName);
    });

    // Simple boolean checks
    if (uiApp.userHasAllRoles(["admin", "super_user"])) {
        // ...
    }
}

Summary Reference

Method	Context	Return Type
`useGetInfos()`	React	`IUserInfos \| undefined`
`useLogOut()`	React	`() => void`
`req.role_getUserRoles()`	API	`string[]`
`req.role_assertUserHasOneOfThisRoles()`	API	`void` (Throws 401)
`uiApp.ifUserHasOneOfThisRoles()`	Init	`void` (Callback based)

Dependencies: Most of these utilities require the @jopijs/jopimod_uicore module. If you are using a standard JopiJS template, it is already included as a foundation dependency.