Nova Permissions Laravel Package

Technical Evaluation

Architecture fit

sereny/nova-permissions is a presentation layer, not a permissions engine. It contributes a Nova tool plus two Nova resources (Role, Permission) that read and write the tables owned by spatie/laravel-permission. That distinction is the single most decision-relevant fact about the package, and it should drive how the org scores it.

Consequences for a TPM:

• Fit is conditional, not absolute. The package is only viable if Laravel Nova is already licensed and in production, and if Spatie's permission tables already exist. Absent either precondition, "installing this package" is actually a project to adopt Nova (commercial license, closed source) or to adopt Spatie (schema migration, trait wiring, guard decisions). Those are different, larger decisions being smuggled in under a "lightweight, easy to install" description.
• The authoritative state lives outside the package. All roles, permissions, and assignments reside in standard Spatie tables. The package can be removed without a data migration. This gives us a genuine two-way door — cheap entry, cheap exit — provided we hold one architectural rule: no application or policy code ever imports a Sereny\ class. Authorization binds to Spatie's contract (HasRoles, Gate, policies, can: middleware). If that boundary holds, a stalled package costs us an admin screen, not production access control. If it slips, the exit becomes a refactor.
• It delivers the commodity tier and visibly omits the rest. Basic RBAC admin — role CRUD, grouped permission matrix, user↔role and role↔permission attach/detach, search — is roughly a sprint of bespoke Nova work. ABAC, tenant/team-scoped permissions, approval workflows, SSO/SCIM provisioning, and audit-grade reporting are all absent. That is useful for roadmap framing: it makes the "basic vs. enterprise access governance" conversation concrete rather than hypothetical.

Integration feasibility

Technically straightforward; procedurally full of decisions that must be made before install, not after.

The 20-minute first win is real: expose the tool to super-admins only, create a billing-manager role, tick grouped permissions, assign to a user. That is a sprint of UI work reclaimed. The reclaimable time should be redirected into domain authorization policies — the part that is actually product-specific — not treated as slack.

Technical risk

• Nova majors are the entire risk surface. Nova 4 was a Vue 3/Inertia rewrite; Nova 5 moved again. Third-party Nova tools historically lag majors by weeks to quarters. Every Nova upgrade is a scheduled spike against our authorization test suite, not a click-through.
• Bus factor of one. 87 stars, single-agency maintainer, no commercial SLA, no published compatibility guarantee beyond composer constraints. The 2024-12-27 release indicates active tracking today; it does not forecast the next Nova major.
• The low composite score (2.30) should be interpreted, not obeyed. It is dominated by ecosystem signals that are structurally blind here: Packagist cannot crawl dependents of a package requiring closed-source laravel/nova, so the reported 0 dependents is a measurement artifact, not evidence of no adoption. Score this as unknown adoption, and weight the maintainer-risk and Nova-coupling findings directly instead of via a composite.
• No audit trail. No change history for role or permission mutations. If "who changed whose access, when" is a compliance requirement, this is a scoping blocker now, not a v2 nice-to-have. Mitigation exists (Spatie permission event listener or model observer writing to an append-only log with Auth::id()), but it is work we own.
• Deleting a role is destructive by design. The UI will let an admin delete a role that four people depend on, and Spatie's cascade drops the model_has_roles rows. Needs a policy blocking deletion of canonical seeder-defined roles plus reviewed confirmation copy.
• Taxonomy drift. A grouped permission matrix makes it trivially easy to end up with view invoices, Invoices-View, and invoice_view in the same afternoon. This is the most likely ongoing source of defects, and it is a governance problem the package cannot solve.

Key questions to resolve before committing

1. Is Nova already licensed, and which major? What is our upgrade cadence, and who owns the spike each time?
2. Are Spatie teams enabled? This changes the semantics of every role created through the screen and cannot be retrofitted cheaply.
3. Which guards are in play, and does every permission row carry the expected guard_name?
4. Is audit-grade access reporting required now, in the next two quarters, or not at all? If now — stop, this package alone does not satisfy it.
5. Who owns the permission taxonomy (naming convention, review of new permissions like migrations)?
6. Will we enforce "no Sereny\ imports in app or policy code" in code review, and who is accountable for that boundary?
7. What is the documented manual fallback when the admin screen breaks?

Integration Approach

Stack fit

Fits cleanly into a Laravel + Nova + Spatie stack (PHP 8.x, Nova 4/5, spatie/laravel-permission 6.x). It is additive — no schema of its own, no middleware, no route rewriting beyond registering a tool. The mismatch case is any environment where Nova is not already the admin surface; there, the cost baseline is Nova licensing plus a UI rewrite, and this package's 20-minute install figure is misleading.

Migration path

Three distinct starting states, with different sequencing and different levels of effort:

• Greenfield RBAC (recommended path). Install Spatie first, publish config, run migrations, decide teams/guards, seed the canonical taxonomy, then add the Nova UI as a convenience layer. The UI is for assigning users to roles — it is never the source of truth.
• Retrofit onto existing Spatie data. Lowest-friction case. Add the package, register the tool and resources, verify the existing role/permission rows render correctly. Validate with $user->getAllPermissions()->pluck('guard_name')->unique() before building anything on top.
• Replacement of a prior UI. Swapping from vyuldashev/nova-permission, a hand-rolled screen, or nothing is a composer change plus re-registering the tool. Role and permission data is untouched because it lives in Spatie tables. This is the cheapest migration of the three and the reason the exit is cheap.

Compatibility

Pin exactly three things in composer.json — the package, Nova, and Spatie — and commit the pin with a comment explaining why. A floating constraint on any of the three is how we get a broken admin screen on a Tuesday with no obvious cause. Verify the package's declared Nova constraint in its own composer manifest at each upgrade rather than trusting the README. Confirm vendor namespace and class paths against the autoload block: small Nova packages rename resources between releases more often than expected.

Sequencing

Phase 2 must not start before Phase 1. Exposing the matrix first guarantees taxonomy drift and a UI that becomes the de facto source of truth.

The gate is the one non-negotiable in Phase 2: hiding the tool from navigation is cosmetic. Without a server-side gate, any user who can reach the screen can grant themselves permissions — that is a privilege-escalation path, not a UI nicety.

Operational Impact

Maintenance

Low, bounded, and concentrated at a predictable trigger: Nova majors. Ongoing maintenance is a pin review, a quarterly check that the package still declares a compatible Nova constraint, and ownership of the taxonomy. Budget one spike per Nova upgrade — run it on a branch against the authorization suite, never as a manual click-through. Everything else (Spatie, migrations, guards) is maintenance we would carry with or without this package.

Support

No SLA and a single-agency maintainer mean this cannot become a strategic dependency; treat it as an accelerator. The mitigations are organizational, not technical, and they are cheap:

• A named internal owner for the package and the taxonomy.
• A written manual fallback for granting a role without the UI (User::where('email', ...)->first()->assignRole(...) in tinker), placed where a non-engineer can find it. An admin outage that is an inconvenience is acceptable; one that becomes an incident is not.
• The "no Sereny\ import" rule enforced in review, converting an 87-star dependency into a replaceable-UI decision.

Scaling

Two axes matter:

• Infrastructure. Spatie caches permission lookups per node. With file caches behind a load balancer, a role change in Nova updates one node and produces divergent authorization across the fleet — intermittent, node-dependent, and the nastiest class of bug on this surface. Redis is a requirement, not an optimization. Manual nuke: php artisan permission:cache-reset.
• Taxonomy and UI scale. The grouped matrix is fast at tens of roles; at hundreds of roles and thousands of permissions it becomes a browsing problem. That ceiling is far out for most orgs, but it is the moment where "just add a role in Nova" stops being the right workflow and role templates or seeding become necessary. Worth a note in the ADR rather than a redesign.

Failure modes

Ramp-up

Engineer onboarding is negligible — one config file, two registered resources, one gate. The real ramp-up is operational: a 20-minute walkthrough for the ops lead (create role → tick grouped permissions → assign to a user) is sufficient for day-to-day use. The training that actually matters is governance — publishing the resource.action convention and making clear that the UI assigns users to roles, not defines the permission universe. Direct user→permission grants bypass the role model and produce an access graph nobody can reason about six months later; reserve them for exceptions or disallow them.

Success metrics worth tracking

• Tickets per month for role/permission changes (the recurring operational saving, easiest to quantify post-launch).
• Engineering days not spent on bespoke RBAC resources (one-time, ~1 sprint reclaimed and redirected to domain policies).
• Zero authorization regressions across Nova upgrades (measured by the authorization suite, not by manual verification).
• Zero Sereny\ imports in app/ or policy code (grep-able; the leading indicator of exit cost).