Clearance Laravel Package

Product Decisions This Supports

Build vs. buy for the admin/RBAC surface. The roles/permissions/users CRUD screens are some of the most tedious, least differentiating work in a B2B SaaS. This package ships them (dashboard, permissions, roles, guards, settings, per-user assignment) behind one composer require and one artisan installer. That is a defensible "buy" call: it converts a 4–8 week internal admin build into a spike-and-ship decision, and frees the roadmap for product work.

Whether to sell tiered/delegated administration. The fine-grained write permissions (clearance-roles-write vs. clearance-settings-write vs. clearance-users-write) make "customer admin can manage their own people and roles, but not global configuration" a shippable entitlement boundary rather than a bespoke engineering ask. This directly supports pricing-page decisions: self-serve admin seats, delegated customer admins, partner/reseller consoles.

Multi-tenant and per-entity role models. Contextual authorization (canIn(), hasRoleIn(), @canin, ContextService) lets a user hold a role within a Store, Tenant, or Project rather than globally. That unlocks roadmap items that are otherwise expensive: per-location store managers, per-project contributors, per-workspace admins, marketplace seller permissions. The resolve order (contextual grants → global grants → per-context overrides, deny wins) is explicit enough to spec against and to explain to customers/security reviewers.

Governance and role hierarchy requirements from sales/security. "Ceiling roles" (a child role can never exceed its parent's permission set, enforced on every save) is a product feature, not just a technical one — it's what lets you say yes to enterprise questions about privilege escalation, reseller/partner hierarchies, and access-review posture. Similarly, the reserved clearance-* namespace and deny-authoritative overrides give you a credible least-privilege story.

Whether to adopt this as an opt-in internal tool vs. a customer-facing surface. Modules are individually mountable as Livewire components and the Users module is toggleable. That supports a staged decision: internal-only admin tooling first (low risk), customer-facing delegated admin later (higher risk, needs UX/design review and localization — 9 bundled languages already covers initial EU/LatAm/APAC GTM).

Migration/consolidation decisions for existing installs. clearance:backfill plus a documented Spatie-migration path means adopting this on an app that already has roles/permissions is a real option, not a rewrite. That matters if you're deciding whether to standardize authorization admin across several Laravel services.

Sequencing decision: stopgap vs. platform investment. Use this to satisfy admin-tooling demand now and defer a bespoke authorization platform until you actually hit its limits (ABAC, approval workflows, audit trails, cross-service enforcement).

When to Consider This Package

Consider it when:

• You're on Laravel 12/13, PHP 8.3+, and already using (or about to use) spatie/laravel-permission. It layers on Spatie rather than replacing it and does not alter Spatie's tables.
• A qualified engineering spike is possible and someone owns the fork/vendor risk — this is an early-adopter bet, not a default.
• Your product genuinely needs context-scoped roles (per store/tenant/project) or delegated customer administration. Spatie alone won't give you either, and hand-rolling both is the expensive part.
• You need an internal admin panel fast and are willing to match it to your app's Livewire layout rather than design a bespoke UI.
• You want privilege-escalation guardrails (ceiling roles, reserved permission namespace) as a compliance talking point.

Look elsewhere — or build — when:

• Stack mismatch. This is Livewire 4 + Flux UI. If your product is Inertia + Vue/React, a Filament admin, or a separate SPA, you're adding a second frontend paradigm for one screen set.
• You're already Filament-native. Filament Shield or a few custom Filament resources will feel more idiomatic and reduce moving parts; embedding Livewire components inside Filament pages is possible but adds integration surface.
• Adoption signal is a hard gate. It has 0 GitHub stars and 0 dependents. That's not disqualifying given 370 tests / 1054 assertions and a documented changelog, but it means you are the QA department for your use cases. If your org requires multi-maintainer, multi-year vendor stability (SOC2 vendor review, procurement), default to no.
• You need capabilities it doesn't claim. Audit log of permission changes, approval workflows, SCIM/SSO group sync, attribute-based policies, time-bound/just-in-time access, cross-service enforcement. Plan to build those on top.
• Flux licensing/cost is unresolved. Confirm which Flux tier you need and that its license terms are acceptable for your deployment model before committing — treat this as a procurement blocker, not a footnote.
• Database-backed guards make you nervous. Guards written to the DB and injected into auth.guards at boot is powerful but is a security-sensitive configuration path; if your public auth surface must stay static/config-driven, don't enable that section.
• You need heavy design-system fidelity to an existing admin UI, or deep customization of the panel's UX.
• Small team, no maintenance appetite. MIT license means you can fork, but someone must be willing to.

Non-negotiables if adopted: keep the super_admin_gate_bypass setting off (default) unless you've explicitly accepted an application-wide Gate bypass; pin the version; and treat the panel as internal-first until it's been exercised in production.

How to Pitch It (Stakeholders)

Executive summary (30 seconds). Clearance is a drop-in admin panel for Laravel roles and permissions that would otherwise cost us weeks of undifferentiated engineering. It adds two things we'd have to build ourselves: contextual roles (a user is a manager of a specific store/tenant, not everywhere) and role ceilings (a role can never be granted more than its parent), which are the features that let us sell delegated customer administration and answer enterprise privilege-escalation questions. It's MIT-licensed, installs in one command, and doesn't touch our existing permissions schema. The trade-off is maturity: it's a young, single-maintainer package with no visible community adoption, so we adopt it as a time-boxed, feature-flagged spike, not a permanent platform commitment.

For engineering. composer require rivalex/clearance + php artisan clearance:install handles Spatie setup, migrations, the super_admin role, and the five delegable clearance-*-write permissions; clearance:backfill exists for installs that already have Spatie data. Integration is one trait swap on User (HasClearance supersedes HasRoles, no conflicts). Panel is available at /clearance or as individually mountable Livewire components, using the host app's Livewire layout. Contextual checks are available via canIn(), Blade directives, ContextService, or the Clearance facade — usable from policies and jobs. Test suite is 370 Pest tests / 1054 assertions, which is meaningful but not the same as third-party production mileage.

Proposed pilot (one sprint, clear exit criteria).

1. Install behind a feature flag; scope to internal staff admins only. Do not enable super_admin_gate_bypass; do not enable DB-backed guards.
2. Instrument and verify: does contextual resolution behave correctly for a real tenant/store model? Does the ceiling enforcement actually block the escalation paths we care about? Does the panel match our layout and locale needs?
3. Exit criteria: contextual checks pass for two real product scenarios, no schema conflicts, acceptable install/upgrade story, and an owner identified for pinning/patching.
4. Decision at exit: adopt (wire in, wrap authorization behind a thin adapter so we can swap later), extend (adopt + fork for gaps), or build (keep the requirements doc, drop the dependency).

Risks and mitigations.

• Vendor risk (0 stars, single maintainer) → pin the version, vendor the source, and keep all authorization calls behind our own service boundary so replacement is a contained change. MIT license protects us here.
• Livewire 4 / Flux UI coupling and licensing → validate before the spike starts; it's a go/no-go input, not an implementation detail.
• Security misconfiguration → the ceiling and reserved-clearance-* protections are the selling point, but they only hold if we leave the global gate bypass off and restrict write permissions deliberately.
• Scope creep into "authorization platform" → we're buying an admin UI and a context model, not audit logging or ABAC. If those requirements materialize, that's a separate business case.

What success looks like. Weeks of admin CRUD removed from the roadmap; a shippable answer to "can a customer's own admin manage their team?"; and a documented, reversible dependency decision — with a named owner — rather than an unbudgeted piece of infrastructure nobody signed up to maintain.