Escalated Filament Laravel Package

Technical Evaluation

Architecture fit

• This is a Laravel package that plugs into a Filament panel (Filament 5.7 in the reported test matrix) and depends on escalated-dev/escalated-laravel ^1.9.0. It sits in the authorization/presentation layer of an existing support product: it owns panel resources and pages, but delegates identity, tenancy, and staff-seat resolution to the parent package.
• v1.4.0 introduces two first-class extension points — Support\StaffSeat (wraps escalated-laravel's StaffAccess) and Support\PanelAccess (resolves configured gate names). This is the right shape: gate naming is configurable rather than hard-coded, and seat checks are centralized instead of scattered across resources.
• The change is predominantly a security correction, not a feature release. The release notes state plainly that agentGate() / adminGate() were documented but never read, meaning every prior version exposed webhooks, API tokens, roles, automations, macros, skills, custom fields, KB articles, newsletters, reports, settings, and the ticket list to any user who could authenticate to the panel. Any deployment on ≤1.3.x should be treated as having a live authorization gap.

Integration feasibility

• Mechanically low effort: composer bump plus a config check. The real work is a pre-upgrade authorization audit, because enforcement is retroactive and default-deny for anyone outside the gates.
• The upgrade is coupled to a second, larger upgrade. escalated-laravel 1.9 carries its own breaking surface (frontend 0.12, migrations, private attachments, verified guest access, requester-only inbound email replies, tenant staff seats). The plugin upgrade cannot be evaluated in isolation; the two must be planned as one change window.
• Gate naming is configurable (defaults escalated-agent / escalated-admin, or names passed to the plugin), so integration with existing Spatie Permission / Filament Shield role models is feasible, but requires an explicit mapping decision rather than an assumption.

Technical risk — HIGH

• Access-loss risk (primary). Support staff who do not pass the configured gates get a 403 and lose all Escalated navigation. Because navigation disappears rather than erroring visibly, the failure mode presents as "the panel is broken" rather than "you lack a permission," which will generate confused tickets.
• Tenant-mode risk. With tenancy enabled, a global agent/admin flag is insufficient; a tenant-local seat via TenantResolver::isAgent/isAdmin is also required. Hosts that granted access purely through global roles will silently lose per-account access.
• Picker degradation. ApiTokenResource::tokenUserOptions() and the skill agent picker now list only seated agents. Where seats have not been backfilled, admins will see truncated or empty pickers and may misread this as data loss.
• Non-interactive callers. Automations, webhooks, and queued jobs that resolve a panel user identity may now hit gate checks outside an HTTP request context. This is not addressed in the notes and is the most likely source of post-deploy runtime failures.
• Additive authorization semantics. Existing model policies still apply on top, so effective access becomes gate AND policy AND (tenant seat). Overly broad policies that previously masked the missing gate will no longer grant access — expect "it worked before" reports from teams whose access depended on permissive policies.
• Vendor patch fragility. The ViewErrorBag Livewire patch script is a monkey-patch against Livewire internals, now matching 4.4 as well as 4.3. It will break on the next Livewire minor. Low user impact but a recurring test-suite interruption.

Key questions

1. Which gates are actually configured in our panel, and does every current Escalated user resolve to escalated-agent or escalated-admin? Can we produce that audit query before touching prod?
2. Are gates driven by Laravel Gate::define, Spatie permissions, or Filament Shield — and is the mapping 1:1 or does it need translation?
3. In tenant mode, how many users hold the global flag without a seat in each active account? Who owns the backfill?
4. Do any service accounts, integration users, or API token owners exist that legitimately need panel access but are not human staff?
5. Are automations, webhooks, or scheduled jobs dependent on panel-user authorization? What happens to them post-enforcement?
6. What is the rollback path — is downgrading to 1.3.x acceptable given it reopens the authorization gap?

Integration Approach

Stack fit

• Assumes a Laravel app on a Filament 5.x panel with Livewire 4.3/4.4. The dependency chain (escalated-laravel ^1.9.0 → frontend 0.12) means the host must be current on Filament and Livewire; teams pinned to older Filament should not attempt this upgrade opportunistically.
• Authorization composes cleanly with existing Laravel gates and with policy-based control — no new auth subsystem is introduced. That is the right integration model for a host app with an established role scheme.
• Support\PanelAccess gives us a supported seam for custom gate names, which avoids forking the package to match our naming conventions.

Migration path

1. Audit first, in staging. Enumerate current Escalated users and evaluate them against the intended gates plus tenant seats. Produce a diff of who loses access.
2. Confirm escalated-laravel 1.9 prerequisites — migrations, frontend 0.12, private attachments, verified guest access, requester-only inbound email replies, tenant staff seats. Complete that release's upgrade notes before starting on the plugin.
3. Upgrade the parent package, run migrations, verify no regressions in isolation.
4. Upgrade the plugin to 1.4.0 and immediately verify: agent access to tickets/canned responses/dashboard, admin access to all other resources, and 403 + hidden navigation for a control user with neither gate.
5. Backfill tenant seats and re-verify pickers are populated.
6. Re-verify non-interactive paths — automations, webhooks, queued jobs — with a real trigger, not just a unit test.

Compatibility

• Backward compatibility is behavioral, not API: no method signatures appear removed, but effective permissions narrow sharply. Treat as a major-version-style change for planning purposes.
• Model policies remain honored and are evaluated in addition to gates, so no policy rewrite is required — but policies that were the only control on ungoverned resources (API tokens, roles, settings) should be reviewed, since they were previously carrying authorization that was assumed to be handled by the gates.
• The Livewire patch script expansion is test-infrastructure only; it does not change runtime behavior.

Sequencing

• Do not combine this with unrelated feature work. Budget a dedicated change window with a named owner for the gate audit and a named owner for tenant seat backfill.
• Stage → audit → parent package → plugin → access verification → comms → prod. Comms should precede the prod deploy, not follow it, since the visible symptom is missing navigation.

Operational Impact

Maintenance

• Steady state is low: gate resolution is centralized in PanelAccess, seat logic in StaffSeat, so future authorization changes are single-point edits.
• The Livewire ViewErrorBag vendor patch is the standing maintenance liability — it requires review on every Livewire bump and can block CI on an otherwise unrelated upgrade. Track it as a known debt item with an owner.
• Pin escalated-laravel to ^1.9.0 and treat future 1.x minors as reviewable, since this release demonstrates the parent package can ship breaking authorization changes in a minor.

Support

• Expect a short, sharp spike in 403 and "missing menu" tickets at rollout, concentrated in the first 48 hours and in tenant-mode accounts.
• Prepare a support runbook: how to check a user's gate assignment, how to check their tenant seat, and who is authorized to grant either. Tier-1 should be able to resolve "I can't see Escalated" without escalation to engineering.
• Second-order ticket class: admins reporting empty API token or skill agent pickers. This is a seating problem, not a bug — worth a canned response.

Scaling

• Per-request gate checks are cheap. The seat-based filtering on the two pickers adds tenant-membership lookups; at large user counts within a single account, watch picker query latency and consider whether the option list needs pagination or search.
• Tenant seat backfill should be scripted and idempotent; manual seat assignment does not scale past a few dozen accounts and is error-prone in exactly the way that produces silent access gaps.

Failure modes

• Silent lockout: user authenticated but gate-less → 403 and no navigation. Hardest to diagnose because the app looks fine to everyone else.
• Global-flag-only users in tenant mode: appear privileged in admin screens but are refused and absent from pickers. Particularly confusing for administrators.
• Unseated pickers: empty or truncated lists read as data loss.
• Background authorization failures: automations or jobs failing on gate checks outside a request, surfacing as missed SLAs rather than errors.
• Vendor patch drift: CI breaks on a Livewire bump; risk of a release being cut with the test suite skipped.

Ramp-up

• Engineering: ~1–2 days for the coupled upgrade and verification, dominated by the gate audit rather than the code change.
• Operations/support enablement: half a day for runbook and comms drafting; the 403 spike is proportional to how well the pre-upgrade audit was communicated.
• Admin/tenant-owner enablement: required in tenant mode. Tenant owners need to understand that a global role is no longer sufficient and that seats are the operative control.
• Overall: proceed, but treat as a security-driven breaking change with a mandatory pre-flight audit. The security upside — closing a documented-but-unenforced authorization gap across API tokens, roles, webhooks, and settings — clearly justifies the upgrade; the risk is entirely in execution and communication, not in the change itself.