Skip to content
Services Technical Documentation

Utilities and guardrails

Utilities and guardrails

Why this page exists

Many cross-cutting invariants in the app are not owned by a page or service. They live in utility modules that are reused by the API client, auth layer, workspace views, and document-processing screens.

Security-sensitive helpers

RBAC

src/utils/rbac.js is the single source of truth for frontend admin access checks.

  • canAccessAdminPortal(role, is_admin) decides whether a user can see the admin portal.
  • resolveEffectiveRole(tenantBranding, currentTenant, backendUser, msalRole) resolves the role precedence chain used by the admin gate.

Sanitization

src/utils/sanitize.js validates endpoint paths and strips unsafe text from backend error messages before they reach the UI.

Secure logging

src/utils/secureLogger.js redacts emails, bearer tokens, UUIDs, IP addresses, and other PII before writing to console-like sinks.

Cache and session helpers

src/utils/apiCache.js and related token-cache helpers are used by the API client to avoid redundant network work and to coordinate token refresh.

Data and schema helpers

  • schemaUtils.js flattens nested schema field trees into displayable rows and paths.
  • dataNormalization.js unwraps and normalizes backend extraction payloads.
  • diffUtils.js computes human-readable differences.
  • validators.js contains input validation helpers.
  • fileTypeUtils.js and fileDownload.js support document/file handling.
  • promptText.js holds prompt string utilities.

Important invariants

  • Endpoint validation should happen before URL construction.
  • Logged errors should not leak raw secrets or HTML fragments.
  • Admin access must go through the centralized RBAC helpers rather than ad hoc checks.
  • Schema utilities must preserve path semantics because other pages rely on those paths for selection and display.
  • Data normalization should preserve meaningful backend payload shape while removing placeholder “not found” text.

Evidence-backed tests

  • tests/unit/rbac.test.js
  • tests/unit/secureLogger.test.js
  • tests/unit/schemaUtils.test.js
  • tests/unit/dataNormalization.test.js
  • tests/unit/diffUtils.test.js
  • tests/unit/sanitize.test.js
  • tests/unit/validators.test.js
  • tests/unit/apiCache.test.js
  • tests/unit/jsonUtils.test.js
  • tests/unit/parseSchemaValue.test.js
  • tests/unit/dataFiltering.test.js

Practical guidance

If a new page or service needs custom validation or logging, prefer adding logic here rather than duplicating the rule in a component. That keeps security and normalization rules testable from one place.