RBAC for a Custom CRM: React + Node.js Design Guide

Five tables cover most CRMs. Seed permissions from code; let admins manage roles.

CREATE TABLE permissions (
  key         text PRIMARY KEY,        -- 'lead:edit', 'invoice:approve'
  description text NOT NULL
);

CREATE TABLE roles (
  id   serial PRIMARY KEY,
  name text UNIQUE NOT NULL            -- 'Sales Rep', 'Accounts Manager'
);

CREATE TABLE role_permissions (
  role_id        int  REFERENCES roles(id) ON DELETE CASCADE,
  permission_key text REFERENCES permissions(key) ON DELETE CASCADE,
  PRIMARY KEY (role_id, permission_key)
);

CREATE TABLE user_roles (
  user_id int REFERENCES users(id) ON DELETE CASCADE,
  role_id int REFERENCES roles(id) ON DELETE CASCADE,
  PRIMARY KEY (user_id, role_id)
);

-- users table already exists; add the attributes record rules need
ALTER TABLE users ADD COLUMN branch_id int;

authz.ts: one function decides; routes declare what they need.

import type { Request, Response, NextFunction } from "express";

type Scope = "own" | "branch" | "all";
type User = { id: number; branchId: number | null; permissions: Set<string> };
type OwnedRecord = { ownerId: number; branchId: number | null };

const ORDER: Scope[] = ["own", "branch", "all"];

/** Highest scope the user holds for an action, or null if none. */
export function scopeFor(user: User, action: string): Scope | null {
  for (const scope of [...ORDER].reverse()) {
    if (user.permissions.has(`${action}:${scope}`)) return scope;
  }
  return null;
}

export function can(user: User, action: string, record?: OwnedRecord): boolean {
  const scope = scopeFor(user, action);
  if (!scope) return false;
  if (!record || scope === "all") return true;
  if (scope === "branch") return record.branchId !== null && record.branchId === user.branchId;
  return record.ownerId === user.id; // "own"
}

/** Route-level guard: the user needs the action at some scope. */
export function requirePermission(action: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    const user = req.user as User | undefined;
    if (user && scopeFor(user, action)) return next();
    logDenial(user?.id, action, req.originalUrl);
    return res.status(403).json({ error: "forbidden" });
  };
}

Translate the user's scope into a WHERE clause for list endpoints.

export function leadVisibilityFilter(user: User): { sql: string; params: unknown[] } {
  switch (scopeFor(user, "lead:view")) {
    case "all":    return { sql: "TRUE", params: [] };
    case "branch": return { sql: "branch_id = $1", params: [user.branchId] };
    case "own":    return { sql: "owner_id = $1", params: [user.id] };
    default:       return { sql: "FALSE", params: [] };
  }
}

// GET /leads
const f = leadVisibilityFilter(req.user);
const { rows } = await db.query(
  `SELECT id, name, stage FROM leads WHERE ${f.sql} ORDER BY updated_at DESC LIMIT 50`,
  f.params,
);

A permission context and a <Can> wrapper for buttons and menu items.

import { createContext, useContext, type ReactNode } from "react";

const PermissionContext = createContext<Set<string>>(new Set());

export function PermissionProvider({ keys, children }: { keys: string[]; children: ReactNode }) {
  return <PermissionContext.Provider value={new Set(keys)}>{children}</PermissionContext.Provider>;
}

export function useCan(action: string) {
  const perms = useContext(PermissionContext);
  return ["own", "branch", "all"].some((s) => perms.has(`${action}:${s}`));
}

export function Can({ action, children }: { action: string; children: ReactNode }) {
  return useCan(action) ? <>{children}</> : null;
}

// Usage
<Can action="invoice:approve">
  <button type="button" onClick={approve}>Approve invoice</button>
</Can>