Nova Role Manager Laravel Package

Technical Evaluation

Architecture fit

• Laravel/Nova vendor tool (routes under /nova-vendor/role-manager/) that sits on top of Spatie laravel-permission and exposes role/permission writes through the Nova admin surface. It is a thin admin-plane package, not a runtime authorization dependency — application authorization still runs through Spatie gates/policies. That keeps blast radius contained to the admin UI/API.
• v1.2.1 is a security release (privilege escalation) plus a config-correctness fix and first test suite. This materially changes the technical posture of the package from "unassessed, unverified" to "has a known-fixed authz bypass and now has regression coverage on the affected endpoints."
• Centralising all three write endpoints (save, toggle, bulk-toggle) behind one guard that checks both edit_permission and protected_roles is the right architectural move: authorization becomes a single choke point rather than per-endpoint duplication, which is what caused the bypass.

Integration feasibility

• Low-to-moderate. Standard install path: Composer require → publish config (role-manager.role_model, protected_roles, edit_permission) → register tool in NovaServiceProvider. The role_model fix means non-default Spatie setups (renamed permission.table_names.roles or a custom Role model) are now supported without code changes — a real unblocker for tenants with custom schemas.
• Requires a Nova licence and a Nova version compatible with the package's constraints; confirm Laravel/PHP/Spatie major-version support before committing.

Technical risk

• Highest risk: prior versions are vulnerable. Any deployment on <1.2.1 with protected_roles configured (e.g. SUPER_ADMIN) has had an open path for anyone with Nova tool access to grant/revoke permissions on protected roles via direct POST to the toggle endpoints. Treat as a potential incident, not just an upgrade.
• Fail-closed behaviour is now implied (single guard checks edit_permission and protected_roles), which is correct but will surface as 403s for any script, saved request, or custom UI that previously relied on the bypass.
• Behavioural break (not a declared API break): clients calling /toggle or /bulk-toggle on protected roles will now be denied. This is intentional but is a de-facto breaking change for automation.
• Test coverage is narrow: Pest + Orchestra Testbench covers role permission endpoints only. Role CRUD, the bulk-toggle transaction semantics, and Nova UI components remain unverified.
• No security advisory/CVE reference or explicit "affected versions" statement in the notes — a gap for AppSec sign-off.

Key questions

• What are the exact version constraints (Laravel, Nova, PHP, spatie/laravel-permission) and is this package actively maintained between releases?
• Is edit_permission a Nova ability/gate string evaluated via Gate::allows, and does it apply to the Nova UI as well as the HTTP endpoints, or only the endpoints?
• How are protected_roles matched — role name, id, or model instance? Case sensitivity? Does it cover wildcards?
• Is bulk-toggle atomic (DB transaction) and per-item validated, or does one protected role in the payload abort the whole batch?
• Are there other write surfaces not covered by the shared guard (user↔role assignment, role deletion/rename, permission CRUD)?
• Is there an audit trail for permission changes? Nothing in the notes suggests one — that's a compliance gap for admin-plane mutations.
• Does 1.2.1 ship any migration or config additions, or is it drop-in for existing installs?

Integration Approach

Stack fit

• Fits a conventional Laravel + Nova + Spatie permission stack, including custom role models and renamed permission tables after this release. Multi-tenant setups that map roles to tenant scopes need explicit validation, since protected_roles appears to be a global config list rather than per-tenant.
• Admin-plane only: no impact on request-path authorization performance.

Migration path

1. Patch immediately (^1.2.1 / >=1.2.1, pin minimum — ^1.2.0 may resolve to a vulnerable version depending on lockfile state). Ship as a security hotfix through the normal change process if a CAB exists.
2. Publish/verify config: confirm role-manager.role_model points at the real model, protected_roles lists every role that must never be mutated in the UI (super admin, break-glass, service roles), and edit_permission is a tightly held ability.
3. Publish a Nova tool registration check and smoke-test all three write endpoints, including a negative test that a protected role is rejected on toggle and bulk-toggle.
4. Audit: query logs/APM for POST /nova-vendor/role-manager/role-permissions/toggle and /bulk-toggle on pre-patch builds; reconcile any permission changes on protected roles.

Compatibility

• No declared breaking API change, but the security fix changes observable behaviour (403s where writes previously succeeded). Confirm no internal runbook, script, or Terraform/seed automation calls these endpoints directly.
• Custom role models now validate correctly; conversely, a mis-set role_model will now fail validation — verify config before rollout rather than after.
• Nova major-version coupling is the long-term compatibility risk; plan to re-verify this package on every Nova upgrade.

Sequencing

1. Security patch + config verification (same change window).
2. Post-patch audit of pre-patch admin activity.
3. Wire the package's new Pest suite into CI; add our own integration tests for the guard (protected role + missing edit_permission cases).
4. Only then expand usage (e.g. broader role-management delegation) once the guard is proven in our environment.

Operational Impact

Maintenance

• Low code footprint, but security-sensitive surface. Adopt a policy of tracking releases promptly — this package's failure mode is silent privilege escalation, not a crash.
• The new Pest/Orchestra Testbench suite is the main maintainability win: it gives upstream regression signal and a harness we can extend for our own protected-role matrix.
• Dependency drift across Nova (major-version cadence) and Spatie permission is the dominant ongoing maintenance cost.

Support

• Small/unknown maintainer footprint typical of Nova vendor tools — assume best-effort upstream support. We should retain the ability to fork or vendor the guard logic if upstream stalls.
• No advisory channel evidenced; add this package to manual security-watch rather than relying on composer audit.

Scaling

• Negligible runtime scaling concern: admin-plane, low QPS, no request-path involvement.
• bulk-toggle is the only scaling-adjacent endpoint — validate batch size limits and that large payloads don't produce partial writes or long-held transactions.
• Spatie permission cache invalidation on write is handled upstream; confirm toggles flush the cache so grants take effect immediately.

Failure modes

• Silent authz bypass (pre-1.2.1): the historical failure. Mitigated now; must be assumed to have occurred.
• Fail-closed lockout: if edit_permission isn't granted or protected_roles is over-broad, admins lose the ability to manage roles entirely — including break-glass recovery. Document the config-based recovery path (edit config / direct DB) before rollout.
• Config drift: wrong role_model → validation rejections on every write, surfacing as generic 422s.
• Partial bulk writes: unverified transactionality in bulk-toggle remains the top residual technical unknown.
• No audit trail: permission mutations on privileged roles are not evidenced as logged; this is the biggest residual operational/compliance risk after the patch.

Ramp-up

• One backend engineer, ~1–2 days to patch, verify config, and write the guard regression tests. AppSec review required given the escalation history — budget a short security sign-off rather than treating this as a routine dependency bump.
• Low knowledge-transfer burden; the shared-guard design makes the authorization model easy to explain in a runbook.