@epcare/esm-report-builder 0.1.1-pre.76 → 0.1.1-pre.78

package/src/components/linelist/linelist-dashboard.page.component.tsx

@@ -49,6 +49,8 @@ import {
   parseLinelistConfig,
 } from '../../resources/linelist/linelist-reports.api';
 import { listReportCategories, type ReportCategoryDto } from '../../resources/report-category/report-category.api';
+import { RB } from '../../constants/privileges';
+import { useReportBuilderPrivileges } from '../../hooks/use-report-builder-privileges';
 import { listDataThemes, type DataThemeDto } from '../../resources/theme/data-theme.api';
 import type { LinelistRowGrain } from '../../types/linelist-types';
 
@@ -74,6 +76,8 @@ interface ReportWithMetadata extends LinelistReportDefinitionDto {
 }
 
 const LinelistReportsPage: React.FC<Props> = () => {
+  const { has: hasPrivilege } = useReportBuilderPrivileges();
+  const canCreateLinelist = hasPrivilege(RB.REPORT_ADD, RB.REPORT_EDIT);
   const navigate = useNavigate();
 
   const [reports, setReports] = useState<ReportWithMetadata[]>([]);
@@ -493,14 +497,16 @@ const LinelistReportsPage: React.FC<Props> = () => {
 
               {/* Action buttons */}
               <div className={styles.filterActions}>
-                <Button
-                  kind="ghost"
-                  size="md"
-                  renderIcon={Add}
-                  onClick={() => navigate('/linelist/new')}
-                >
-                  Create linelist report
-                </Button>
+                {canCreateLinelist && (
+                  <Button
+                    kind="ghost"
+                    size="md"
+                    renderIcon={Add}
+                    onClick={() => navigate('/linelist/new')}
+                  >
+                    Create linelist report
+                  </Button>
+                )}
                 {selectedReports.size > 0 && (
                   <Button
                     kind="primary"
@@ -590,11 +596,12 @@ const LinelistReportsPage: React.FC<Props> = () => {
               ? 'No reports match your filters. Try adjusting your search criteria.'
               : 'Get started by creating your first linelist report.'}
           </p>
-          {!(searchQuery || statusFilter !== 'all' || categoryFilter || rowTypeFilter !== 'all') && (
-            <Button kind="primary" renderIcon={Add} onClick={() => navigate('/linelist/new')}>
-              Create Linelist Report
-            </Button>
-          )}
+          {!(searchQuery || statusFilter !== 'all' || categoryFilter || rowTypeFilter !== 'all') &&
+            canCreateLinelist && (
+              <Button kind="primary" renderIcon={Add} onClick={() => navigate('/linelist/new')}>
+                Create Linelist Report
+              </Button>
+            )}
         </Tile>
       ) : (
         <>

package/src/components/report/report-dashboard.page.component.tsx

@@ -31,6 +31,8 @@ import { Play, Add, Renew } from '@carbon/react/icons';
 
 import Header from '../shared/header/header.component';
 import { listReports, compileReport, type ReportDto } from '../../resources/report/reports.api';
+import { RB } from '../../constants/privileges';
+import { useReportBuilderPrivileges } from '../../hooks/use-report-builder-privileges';
 import { listReportCategories, type ReportCategoryDto } from '../../resources/report-category/report-category.api';
 import ExportReportModal from '../import-export/export-report-modal.component';
 
@@ -44,6 +46,8 @@ type ReportWithMetadata = ReportDto & {
 };
 
 const ReportDashboardPage: React.FC = () => {
+  const { has: hasPrivilege } = useReportBuilderPrivileges();
+  const canCreateReport = hasPrivilege(RB.REPORT_ADD, RB.REPORT_EDIT);
   const { t } = useTranslation();
   const navigate = useNavigate();
 
@@ -362,14 +366,16 @@ const ReportDashboardPage: React.FC = () => {
               Compile Selected ({selectedReports.size})
             </Button>
           )}
-          <Button
-            kind="ghost"
-            size="md"
-            renderIcon={Add}
-            onClick={() => navigate('/new')}
-          >
-            Create Report
-          </Button>
+          {canCreateReport && (
+            <Button
+              kind="ghost"
+              size="md"
+              renderIcon={Add}
+              onClick={() => navigate('/new')}
+            >
+              Create Report
+            </Button>
+          )}
           <Button
             kind="ghost"
             size="md"

package/src/components/report/report-editor.page.component.tsx

@@ -34,6 +34,8 @@ import {
 import { listSections } from '../../resources/report-section/report-sections.api';
 import { listReportCategories, type ReportCategoryDto } from '../../resources/report-category/report-category.api';
 import CompileSetupModal, { type CompileSetupResult } from '../shared/compile-setup-modal.component';
+import { RB } from '../../constants/privileges';
+import { useReportBuilderPrivileges } from '../../hooks/use-report-builder-privileges';
 
 type TabKey = 'details' | 'definition' | 'design';
 type BuilderMode = 'create' | 'edit';
@@ -118,6 +120,7 @@ function safeParseJson(raw?: string | null): any {
 export default function ReportEditorPage() {
   const { t } = useTranslation();
   const { reportId } = useParams();
+  const { has: hasPrivilege } = useReportBuilderPrivileges();
 
   const mode: BuilderMode = reportId ? 'edit' : 'create';
 
@@ -448,7 +451,9 @@ export default function ReportEditorPage() {
   }, []);
 
   const canSave = Boolean(form.name.trim()) && !saving && !loading;
-  const canCompile = Boolean((savedReport?.uuid || reportId || form.name.trim()) && !saving && !compiling && !loading);
+  const canCompile =
+      hasPrivilege(RB.REPORT_COMPILE) &&
+      Boolean((savedReport?.uuid || reportId || form.name.trim()) && !saving && !compiling && !loading);
 
   return (
       <>

package/src/components/report-sections/report-sections-page.component.tsx

@@ -18,6 +18,8 @@ import { useTranslation } from 'react-i18next';
 
 import Header from '../shared/header/header.component';
 import CreateSectionModal from './create-report-section-modal.component';
+import { RB } from '../../constants/privileges';
+import { useReportBuilderPrivileges } from '../../hooks/use-report-builder-privileges';
 import type { CreateSectionPayload, SectionIndicatorRef } from './section-types';
 import SectionPreviewModal from './report-section-preview-modal.component';
 import styles from './sections-page.scss';
@@ -41,6 +43,10 @@ function countIndicatorsFromConfig(section: ReportSectionDto): number {
 const SectionsPage: React.FC = () => {
     const { t } = useTranslation();
 
+    const { has: hasPrivilege } = useReportBuilderPrivileges();
+    const canAddSection = hasPrivilege(RB.SECTION_ADD, RB.SECTION_EDIT);
+    const canPreviewSection = hasPrivilege(RB.SQL_EXECUTE);
+
     const [q, setQ] = React.useState('');
     const [openCreate, setOpenCreate] = React.useState(false);
 
@@ -193,9 +199,11 @@ const SectionsPage: React.FC = () => {
             <div className={styles.sectionsPage}>
                 <div className={styles.headerRow}>
                     <h3 className={styles.title}>{t('sections', 'Sections')}</h3>
-                    <Button size="sm" kind="primary" renderIcon={Add} onClick={() => setOpenCreate(true)}>
-                        {t('createSection', 'Create Section')}
-                    </Button>
+                    {canAddSection && (
+                        <Button size="sm" kind="primary" renderIcon={Add} onClick={() => setOpenCreate(true)}>
+                            {t('createSection', 'Create Section')}
+                        </Button>
+                    )}
                 </div>
 
                 <div className={styles.surface}>
@@ -238,8 +246,12 @@ const SectionsPage: React.FC = () => {
                                                     return (
                                                         <TableCell key={cell.id}>
                                                             <OverflowMenu data-testid={`section-actions-${row.id}`} size="sm" ariaLabel="Actions" flipped>
-                                                                <OverflowMenuItem itemText="Preview" onClick={() => openPreview(row.id)} />
-                                                                <OverflowMenuItem itemText="Edit" onClick={() => openEdit(row.id)} />
+                                                                {canPreviewSection && (
+                                                                    <OverflowMenuItem itemText="Preview" onClick={() => openPreview(row.id)} />
+                                                                )}
+                                                                {canAddSection && (
+                                                                    <OverflowMenuItem itemText="Edit" onClick={() => openEdit(row.id)} />
+                                                                )}
                                                             </OverflowMenu>
                                                         </TableCell>
                                                     );

package/src/components/security/access-denied-page.component.tsx

@@ -0,0 +1,69 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import { Button, InlineNotification, Tag } from '@carbon/react';
+import { useNavigate } from 'react-router-dom';
+
+import { rbDisplay, RB } from '../../constants/privileges';
+import { useReportBuilderPrivileges } from '../../hooks/use-report-builder-privileges';
+import styles from './access-denied-page.scss';
+
+interface AccessDeniedPageProps {
+    /** Full privilege names, e.g. `Task: reportbuilder.report.edit`. */
+    requiredPrivileges?: string[];
+}
+
+const AccessDeniedPage: React.FC<AccessDeniedPageProps> = ({ requiredPrivileges }) => {
+    const { t } = useTranslation();
+    const navigate = useNavigate();
+    const { has } = useReportBuilderPrivileges();
+    const privileges = requiredPrivileges ?? [];
+
+    return (
+        <div className={styles.container}>
+            <InlineNotification
+                lowContrast
+                kind="error"
+                title={t('accessDenied', 'Access denied')}
+                subtitle={t(
+                    'accessDeniedSubtitle',
+                    'Your account does not have permission to open this page.',
+                )}
+                hideCloseButton
+            />
+
+            {privileges.length > 0 && (
+                <div className={styles.section}>
+                    <p className={styles.label}>
+                        {t('requiredPrivileges', 'Required privilege(s):')}
+                    </p>
+                    <div className={styles.tags}>
+                        {privileges.map((privilege) => (
+                            <Tag key={privilege} type="red">
+                                {rbDisplay(privilege)}
+                            </Tag>
+                        ))}
+                    </div>
+                    <p className={styles.hint}>
+                        {t(
+                            'accessDeniedHint',
+                            'Ask your administrator to grant you the report builder role carrying these privileges.',
+                        )}
+                    </p>
+                </div>
+            )}
+
+            <div className={styles.actions}>
+                {has(RB.REPORT_VIEW) && (
+                    <Button kind="primary" onClick={() => navigate('/')}>
+                        {t('goToHome', 'Go to Home')}
+                    </Button>
+                )}
+                <Button kind="secondary" onClick={() => navigate(-1)}>
+                    {t('goBack', 'Go back')}
+                </Button>
+            </div>
+        </div>
+    );
+};
+
+export default AccessDeniedPage;

package/src/components/security/access-denied-page.scss

@@ -0,0 +1,39 @@
+@use '@carbon/styles/scss/spacing';
+@use '@carbon/type' as type;
+
+.container {
+  display: flex;
+  flex-direction: column;
+  gap: spacing.$spacing-06;
+  max-width: 40rem;
+  padding: spacing.$spacing-07 spacing.$spacing-06;
+}
+
+.section {
+  display: flex;
+  flex-direction: column;
+  gap: spacing.$spacing-03;
+}
+
+.label {
+  @include type.type-style('body-01');
+
+  color: var(--cds-text-secondary);
+}
+
+.tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: spacing.$spacing-02;
+}
+
+.hint {
+  @include type.type-style('body-01');
+
+  color: var(--cds-text-secondary);
+}
+
+.actions {
+  display: flex;
+  gap: spacing.$spacing-03;
+}

package/src/components/security/privilege-route.component.test.tsx

@@ -0,0 +1,79 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { MemoryRouter } from 'react-router-dom';
+
+jest.mock('@openmrs/esm-framework', () => ({
+    useSession: jest.fn(),
+}));
+
+import { useSession } from '@openmrs/esm-framework';
+import { RB } from '../../constants/privileges';
+import PrivilegeRoute from './privilege-route.component';
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+function sessionWith(privileges: string[], authenticated = true) {
+    return {
+        authenticated,
+        user: {
+            uuid: 'u-1',
+            display: 'User',
+            privileges: privileges.map((name) => ({ uuid: name, name, display: name })),
+            roles: [],
+        },
+    } as any;
+}
+
+function renderAt(route: string, ui: React.ReactElement): { text: () => string; unmount: () => void } {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    act(() => {
+        root.render(<MemoryRouter initialEntries={[route]}>{ui}</MemoryRouter>);
+    });
+    return {
+        text: () => container.textContent ?? '',
+        unmount: () => act(() => root.unmount()),
+    };
+}
+
+describe('PrivilegeRoute', () => {
+    it('renders children when a required privilege is held (any-of)', () => {
+        (useSession as unknown as jest.Mock).mockReturnValue(sessionWith([RB.PACKAGE_EXPORT]));
+        const view = renderAt(
+            '/import-export',
+            <PrivilegeRoute required={[RB.PACKAGE_IMPORT, RB.PACKAGE_EXPORT]}>
+                <div>secret content</div>
+            </PrivilegeRoute>,
+        );
+        expect(view.text()).toContain('secret content');
+        view.unmount();
+    });
+
+    it('renders the access denied page naming the privilege when unauthorised', () => {
+        (useSession as unknown as jest.Mock).mockReturnValue(sessionWith([RB.REPORT_VIEW]));
+        const view = renderAt(
+            '/run',
+            <PrivilegeRoute required={[RB.REPORT_RUN]}>
+                <div>secret content</div>
+            </PrivilegeRoute>,
+        );
+        expect(view.text()).not.toContain('secret content');
+        expect(view.text()).toContain('Access denied');
+        expect(view.text()).toContain('report.run');
+        view.unmount();
+    });
+
+    it('renders nothing and does not crash for an unauthenticated visitor', () => {
+        (useSession as unknown as jest.Mock).mockReturnValue(sessionWith([], false));
+        const view = renderAt(
+            '/',
+            <PrivilegeRoute required={[RB.REPORT_VIEW]}>
+                <div>secret content</div>
+            </PrivilegeRoute>,
+        );
+        expect(view.text()).toBe('');
+        view.unmount();
+    });
+});

package/src/components/security/privilege-route.component.tsx

@@ -0,0 +1,39 @@
+import React, { useEffect } from 'react';
+
+import { useReportBuilderPrivileges } from '../../hooks/use-report-builder-privileges';
+import { redirectToLogin } from '../../utils/api-error.utils';
+import AccessDeniedPage from './access-denied-page.component';
+
+interface PrivilegeRouteProps {
+    /** Privileges granting access; any-of semantics, matching the backend's @Authorized. */
+    required: string[];
+    children: React.ReactNode;
+}
+
+/**
+ * Route guard: renders children only when the signed-in user holds at least one
+ * of the required privileges; otherwise renders the friendly access denied page.
+ * Unauthenticated visitors are sent to the login page instead (401 vs 403).
+ * This is UX only — the backend remains the security boundary.
+ */
+const PrivilegeRoute: React.FC<PrivilegeRouteProps> = ({ required, children }) => {
+    const { has, isAuthenticated } = useReportBuilderPrivileges();
+
+    useEffect(() => {
+        if (!isAuthenticated) {
+            redirectToLogin();
+        }
+    }, [isAuthenticated]);
+
+    if (!isAuthenticated) {
+        return null;
+    }
+
+    if (!has(...required)) {
+        return <AccessDeniedPage requiredPrivileges={required} />;
+    }
+
+    return <>{children}</>;
+};
+
+export default PrivilegeRoute;

package/src/constants/privileges.test.ts

@@ -0,0 +1,53 @@
+import { RB, RB_PREFIX, ROUTE_PRIVILEGES, rbDisplay } from './privileges';
+
+describe('privilege catalog', () => {
+  it('declares exactly the 46 backend privileges', () => {
+    expect(Object.keys(RB)).toHaveLength(46);
+  });
+
+  it('builds every privilege from the canonical prefix', () => {
+    for (const value of Object.values(RB)) {
+      expect(value.startsWith(RB_PREFIX)).toBe(true);
+      // Backend suffixes are lowercase dotted domains/actions
+      expect(value).toMatch(/^Task: reportbuilder\.[a-z.]+$/);
+    }
+  });
+
+  it('keeps report.view matching the backend contract verbatim', () => {
+    expect(RB.REPORT_VIEW).toBe('Task: reportbuilder.report.view');
+    expect(RB.REPORT_EDIT).toBe('Task: reportbuilder.report.edit');
+    expect(RB.SQL_EXECUTE).toBe('Task: reportbuilder.sql.execute');
+    expect(RB.PACKAGE_IMPORT).toBe('Task: reportbuilder.package.import');
+  });
+
+  it('strips the prefix for display', () => {
+    expect(rbDisplay(RB.REPORT_EDIT)).toBe('report.edit');
+  });
+});
+
+describe('route privilege map', () => {
+  it('always requires at least one privilege per guarded route', () => {
+    for (const [route, required] of Object.entries(ROUTE_PRIVILEGES)) {
+      expect(required.length).toBeGreaterThan(0);
+      for (const privilege of required) {
+        expect(Object.values(RB)).toContain(privilege);
+      }
+      expect(route).toMatch(/^\//);
+    }
+  });
+
+  it('covers the landing, run, and admin landing routes', () => {
+    expect(ROUTE_PRIVILEGES['/']).toEqual([RB.REPORT_VIEW]);
+    expect(ROUTE_PRIVILEGES['/run']).toEqual([RB.REPORT_RUN]);
+    expect(ROUTE_PRIVILEGES['/admin']).toEqual([RB.REPORT_VIEW]);
+  });
+
+  it('gives import-export OR semantics (either package privilege)', () => {
+    expect(ROUTE_PRIVILEGES['/import-export']).toEqual([RB.PACKAGE_IMPORT, RB.PACKAGE_EXPORT]);
+  });
+
+  it('does not guard redirect-only routes', () => {
+    expect(ROUTE_PRIVILEGES['/themes']).toBeUndefined();
+    expect(ROUTE_PRIVILEGES['*']).toBeUndefined();
+  });
+});

package/src/constants/privileges.ts

@@ -0,0 +1,118 @@
+/**
+ * Privilege catalog for the report builder.
+ *
+ * Mirrors the backend catalog — api/.../security/ReportBuilderPrivileges.java and
+ * omod/src/main/resources/configuration/privileges/reportbuilder-privileges.csv
+ * (see openmrs-module-report-builder README.md -> Security: Privileges & Roles).
+ * Keep in sync — if the backend catalog changes, this file changes.
+ *
+ * This is the ONLY source file allowed to contain `Task: reportbuilder.` literals.
+ * The one exception is routes.json, whose `privileges` key gates the System
+ * Administration card link declaratively (framework-enforced) — keep that string
+ * in sync with RB.REPORT_VIEW.
+ */
+export const RB_PREFIX = 'Task: reportbuilder.';
+
+const rb = (suffix: string) => `${RB_PREFIX}${suffix}`;
+
+export const RB = {
+  // Report definitions
+  REPORT_VIEW: rb('report.view'),
+  REPORT_ADD: rb('report.add'),
+  REPORT_EDIT: rb('report.edit'),
+  REPORT_PURGE: rb('report.purge'),
+  REPORT_COMPILE: rb('report.compile'),
+  REPORT_RUN: rb('report.run'),
+  // Indicators
+  INDICATOR_VIEW: rb('indicator.view'),
+  INDICATOR_ADD: rb('indicator.add'),
+  INDICATOR_EDIT: rb('indicator.edit'),
+  INDICATOR_PURGE: rb('indicator.purge'),
+  // Report sections
+  SECTION_VIEW: rb('section.view'),
+  SECTION_ADD: rb('section.add'),
+  SECTION_EDIT: rb('section.edit'),
+  SECTION_PURGE: rb('section.purge'),
+  // Data themes
+  THEME_VIEW: rb('theme.view'),
+  THEME_ADD: rb('theme.add'),
+  THEME_EDIT: rb('theme.edit'),
+  THEME_PURGE: rb('theme.purge'),
+  // Dashboards
+  DASHBOARD_VIEW: rb('dashboard.view'),
+  DASHBOARD_ADD: rb('dashboard.add'),
+  DASHBOARD_EDIT: rb('dashboard.edit'),
+  DASHBOARD_PURGE: rb('dashboard.purge'),
+  // Report categories
+  CATEGORY_VIEW: rb('category.view'),
+  CATEGORY_ADD: rb('category.add'),
+  CATEGORY_EDIT: rb('category.edit'),
+  CATEGORY_PURGE: rb('category.purge'),
+  // Age categories & age groups
+  AGEGROUP_VIEW: rb('agegroup.view'),
+  AGEGROUP_ADD: rb('agegroup.add'),
+  AGEGROUP_EDIT: rb('agegroup.edit'),
+  AGEGROUP_PURGE: rb('agegroup.purge'),
+  // Report library
+  LIBRARY_VIEW: rb('library.view'),
+  LIBRARY_ADD: rb('library.add'),
+  LIBRARY_EDIT: rb('library.edit'),
+  LIBRARY_PURGE: rb('library.purge'),
+  // ETL sources
+  ETLSOURCE_VIEW: rb('etlsource.view'),
+  ETLSOURCE_ADD: rb('etlsource.add'),
+  ETLSOURCE_EDIT: rb('etlsource.edit'),
+  ETLSOURCE_PURGE: rb('etlsource.purge'),
+  // ETL health monitors
+  ETLMONITOR_VIEW: rb('etlmonitor.view'),
+  ETLMONITOR_ADD: rb('etlmonitor.add'),
+  ETLMONITOR_EDIT: rb('etlmonitor.edit'),
+  ETLMONITOR_PURGE: rb('etlmonitor.purge'),
+  // Cross-cutting
+  SCHEMA_VIEW: rb('schema.view'),
+  SQL_EXECUTE: rb('sql.execute'),
+  PACKAGE_IMPORT: rb('package.import'),
+  PACKAGE_EXPORT: rb('package.export'),
+} as const;
+
+export type RbPrivilege = (typeof RB)[keyof typeof RB];
+
+/** 'Task: reportbuilder.report.edit' -> 'report.edit' (for display only). */
+export const rbDisplay = (privilege: string) => privilege.replace(RB_PREFIX, '');
+
+/**
+ * Route -> required privileges (any-of semantics: holding at least one grants access).
+ * Mirrors the backend FRONTEND_SECURITY_INSTRUCTIONS.md route table, extended with the
+ * routes it omits (admin/themes, linelist family, dashboards/:code, etl-dashboard,
+ * import-export). `/themes` (redirect) and `*` (fallback) are intentionally absent.
+ */
+export const ROUTE_PRIVILEGES: Record<string, string[]> = {
+  '/': [RB.REPORT_VIEW],
+  '/reports': [RB.REPORT_VIEW],
+  '/new': [RB.REPORT_ADD],
+  '/edit/:reportId': [RB.REPORT_EDIT],
+  '/run': [RB.REPORT_RUN],
+  '/run-reports': [RB.REPORT_RUN],
+  '/indicators': [RB.INDICATOR_VIEW],
+  '/sections': [RB.SECTION_VIEW],
+  '/dashboards': [RB.DASHBOARD_VIEW],
+  '/dashboards/:code': [RB.DASHBOARD_VIEW],
+  '/etl-dashboard': [RB.DASHBOARD_VIEW],
+  '/linelist': [RB.REPORT_VIEW],
+  '/linelist/new': [RB.REPORT_ADD],
+  '/linelist/edit/:reportId': [RB.REPORT_EDIT],
+  '/linelist/run/:reportId': [RB.REPORT_RUN],
+  '/admin': [RB.REPORT_VIEW],
+  '/admin/report-categories': [RB.CATEGORY_VIEW],
+  '/admin/age-categories': [RB.AGEGROUP_VIEW],
+  '/admin/age-groups': [RB.AGEGROUP_VIEW],
+  '/admin/report-library': [RB.LIBRARY_VIEW],
+  '/admin/themes': [RB.THEME_VIEW],
+  '/admin/etl-sources': [RB.ETLSOURCE_VIEW],
+  '/admin/etl-tasks': [RB.PACKAGE_IMPORT],
+  '/admin/etl-browser': [RB.ETLSOURCE_VIEW],
+  '/admin/etl-monitors': [RB.ETLMONITOR_VIEW],
+  '/admin/etl-monitors/builder': [RB.ETLMONITOR_VIEW],
+  '/admin/dashboards': [RB.DASHBOARD_VIEW],
+  '/import-export': [RB.PACKAGE_IMPORT, RB.PACKAGE_EXPORT],
+};