[Georgechisom]

Summary

This PR implements four critical operational and security improvements for Utix, establishing foundations for production readiness and maintainer workflows.

Changes

Role-Based Access Control

Implements a permission system for privileged operations with three roles: viewer, maintainer, and service. All permission checks are enforced server-side and cannot be bypassed through UI manipulation.

Files:
core/auth/types.ts Role and permission type definitions
core/auth/middleware.ts Server-side authorization middleware
core/auth/__tests__/permissions.test.ts Comprehensive permission tests
docs/RBAC.md Complete RBAC documentation

Key Features:
Centralized permission definitions
Server-side enforcement for all privileged actions
Higher-order function wrappers for route protection
Full test coverage for all role-permission combinations

Disaster Recovery Validation

Provides read-only validation checks to verify data integrity after restore or migration operations. Validates core domain invariants including registry consistency and network configuration.

Files:
core/recovery/types.ts Invariant violation type definitions
core/recovery/validator.ts Validation engine and checks
core/recovery/__tests__/validator.test.ts Validator test suite
scripts/validate-recovery.mjs CLI command for recovery validation
docs/DISASTER_RECOVERY.md Recovery validation guide

Key Features:
Detects missing, orphaned, duplicate, and inconsistent records
Read-only by design
Human-readable and JSON output formats
Actionable failure reporting with escalation guidance

Operational Health Dashboard

Aggregates system health indicators, unresolved exceptions, and stale records into a maintainer dashboard for operational monitoring.

Files:
core/health/types.ts Health monitoring type definitions
core/health/monitor.ts Health check engine and reporting
core/health/__tests__/monitor.test.ts Health monitor test suite
scripts/health-check.mjs CLI command for health checks
docs/OPERATIONAL_HEALTH.md Health dashboard documentation

Key Features:
Monitors feature registry, network connectivity, and environment config
Tracks unresolved exceptions with full context
Identifies stale records by age threshold
Human and machine-readable output formats

Bundle Size Budget Enforcement

Enforces per-feature-slice bundle size budgets in CI to prevent dependency bloat. Each lazy-loaded feature has its own budget, preventing one heavy tool from hiding behind another.

Files:
scripts/bundle-budget.mjs Bundle analysis and budget enforcement
bundle-baseline.json Baseline bundle sizes for regression tracking
__tests__/bundle-budget.test.ts Bundle budget configuration tests
docs/BUNDLE_BUDGET.md Bundle budget documentation

Key Features:
Per-feature budgets with configurable limits
Baseline tracking for regression detection
Excludes shared core code from feature attribution
Fails CI on budget violations

Testing

All new features include comprehensive test coverage:
Permission system: All role-permission combinations tested
Recovery validation: All checks executable and produce valid output
Health monitoring: All indicators check properly
Bundle budgets: Configuration and baseline validation

Run tests with:

npm run test

Documentation

Complete documentation added for all features:
docs/RBAC.md Role and permission reference
docs/DISASTER_RECOVERY.md Recovery validation guide
docs/OPERATIONAL_HEALTH.md Health monitoring guide
docs/BUNDLE_BUDGET.md Bundle budget enforcement guide

Main README updated with new commands and operations section.

CI Integration

GitHub Actions workflow updated to run:
Bundle budget checks after build
Disaster recovery validation
Operational health checks

These checks provide early detection of issues before deployment.

Commands

New npm scripts:

npm run recovery:validate  # Run disaster recovery validation
npm run health:check       # Generate operational health report
npm run bundle:check       # Check bundle size budgets

Migration Notes

No breaking changes. All features are additive.

The default user role is viewer, maintaining current behavior. Set UTIX_USER_ROLE environment variable to enable elevated permissions for maintainers.

Bundle baseline is included with initial values. Update with npm run build && node scripts/bundle-budget.mjs --update-baseline when making intentional bundle size changes.

Design Decisions

RBAC Scope: Focused on operational workflows rather than user data access since Utix is read-only by design. Permissions target maintainer tools and admin dashboards.

Recovery Validation: Read-only checks that never modify data. Designed for post-restore verification, not automatic repair.

Health Dashboard: Aggregates multiple health dimensions into single report. Designed for both human review and monitoring system integration.

Bundle Budgets: Per-feature approach aligns with lazy-loaded architecture. Default 150KB budget allows typical implementations while preventing bloat.

Future Work

Extend RBAC when user-facing features require authorization
Add domain-specific recovery checks as data model evolves
Integrate health metrics with external monitoring systems
Refine bundle budgets based on real-world usage patterns

Closes #47
Closes #62
Closes #60
Closes #28

[drips-wave]

@Georgechisom Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits