Statamic A11Y Gate Laravel Package

Technical Evaluation

Architecture fit

• This is a Statamic addon, not a general Laravel package. It integrates by registering a fieldtype, control-panel Vue components, and a Tools page through Statamic's addon service provider, and it ships publishable config and compiled CP assets. Fit is high for Statamic sites, near-zero for plain Laravel apps.
• The product surfaces are: an auto-placed Accessibility field on entries (now correctly listable: false), a per-entry "Check" action, a save-time gate that refuses publishes, and a Tools page with findings lists. Findings reference page content (heading text, image src, link words) and are rendered inside the control panel.
• The addon is deliberately scoped: it refuses the completeness claim WCAG 2.2 AA (colour contrast is explicitly not checked), and v0.10.2 tightened wording from "Anything that would fail WCAG 2.2 AA stops the publish" to "Anything it finds." That is honest positioning — a gate, not a certification — and should be reflected in how we describe it to authors and auditors.

Integration feasibility

• Install path is documented for the first time (composer require, PHP/Statamic floors, optional ext-intl for locale-aware checks, config publish tag, and the two files an uninstall can leave behind). This closes a real onboarding gap.
• The material constraint is that the security fix lives in compiled front-end assets, not only in PHP. composer update alone does not remediate. The deploy must also run php artisan vendor:publish --tag=statamic-a11y-gate --force (or php artisan statamic:install). Environments that treat "composer update + cache clear" as a complete upgrade will remain vulnerable while reporting 0.10.2.
• Pre-1.0 versioning with an observed pattern of corrections to previously published instructions (the 0.8.0 note named --tag=laravel-assets, which publishes nothing for this addon) means version numbers cannot be trusted as an upgrade contract. Pin exact versions and read release notes each bump.

Technical risk

• Stored XSS in the control panel, confirmed on a live panel, affecting ≤0.10.1. A heading containing markup such as <img src=/x.png onerror=...> is escaped on the front end but reached the panel decoded and was rendered via innerHTML. Trigger conditions: an attacker with permission to save a gated entry plants it; it executes in the CP session of an admin who presses Check on that entry or is refused a save of it. That is an author→admin privilege-escalation path exercised during ordinary editorial review.
• Mitigating factors: it requires content-write on a gated entry plus an admin action on that entry, so it is not unauthenticated or fully passive. Aggravating factors: the trigger is a normal workflow step, and the payload survives in stored content indefinitely.
• Residual risk after upgrade is concentrated in deployment: stale published assets, CDN/browser caches, or multi-environment drift where staging is patched and production is not.
• Secondary risks: single-maintainer project, no response-time commitment, public issue tracker named as the sole support channel with no documented private security-disclosure route; and pre-1.0 churn across config keys, asset tags, and CP markup.
• New build-time guard is a genuine quality signal: a test reads the compiled CP stylesheet and fails the build if the addon writes a class the panel cannot draw (the cause of the missing list-disc bullets). Similar guards should be expected for future CP regressions.

Key questions

1. What are the exact Statamic and PHP version floors, and does our target version sit inside them?
2. Does our deploy pipeline publish vendor assets on every release, and can we verify the served asset changed after upgrade?
3. Are we on ≤0.10.1 anywhere — including staging, preview, and multi-tenant environments — and who has content-write on gated entries today?
4. Does a CSP or admin-network restriction currently blunt this class of issue, and would it survive the fix?
5. Where are findings stored and for how long? They embed page content, so retention and access scope need review.
6. Is there a private vulnerability-disclosure channel, or is the public tracker genuinely the only route?
7. What is the performance envelope for Check on large entries and for the Tools page on content-heavy sites?

Integration Approach

Stack fit

• Targets Statamic control panels with Laravel/PHP underneath and Vue-based CP components; findings render through the panel's own component layer. No external service, no queue dependency, and no third-party API is implied.
• The only optional platform dependency called out is ext-intl, which improves locale-aware checks; absence degrades rather than blocks.

Migration path

• Greenfield: install directly at 0.10.2. Do not install 0.10.1 or earlier under any circumstance.
• Existing installs on ≤0.10.1: treat as an incident, not a routine bump. Sequence: composer require the pinned 0.10.2 → php artisan vendor:publish --tag=statamic-a11y-gate --force → php artisan statamic:install if that is our standard → clear config/view caches → confirm the served CP asset hash changed → only then close the ticket.
• Do not use --tag=laravel-assets; the release notes explicitly correct the earlier instruction, which published nothing for this addon.
• Note that --force overwrites published files. If we have local modifications to the addon's config or views, capture them first.

Compatibility

• Pre-1.0 with no semver guarantees. Pin to 0.10.2 exactly and require a release-note read before any bump.
• Watch items already demonstrated: asset publish tag naming, CP CSS class availability, and field configurability (listable). All three have changed or been corrected in this release.
• Uninstall is documented as leaving two files behind; include those in teardown runbooks so orphaned config does not confuse a later reinstall.

Sequencing

1. Security upgrade to 0.10.2 with asset republish, production first if it is the exposed environment.
2. Make vendor asset publishing a mandatory, verified pipeline step — the upgrade is not complete until a post-deploy check confirms the new asset is served.
3. Publish and review config; decide on ext-intl.
4. Enable the gate in a report-only or advisory mode on a subset of entries; confirm author-facing refusal UX before enforcing.
5. Roll out to all gated collections; brief authors on the new reveal behaviour on tablet/small-laptop widths, where a refused save now switches to the tab holding the alert instead of showing only a corner toast.
6. Add the release-note/asset-publish step to the standard addon upgrade checklist, not just this one.

Operational Impact

Maintenance

• Low code footprint, but ongoing attention required: every upgrade may require an asset republish, and the project is pre-1.0 with a visible history of corrective releases.
• Single maintainer with no response-time promise. Budget for the possibility of self-patching or forking, particularly for security issues. This is acceptable for an advisory accessibility tool; it is a heavier decision if the gate becomes publish-blocking for revenue content.

Support

• One channel: the public issue tracker. That is workable for defects and questions, but it is a weak fit for security reporting — there is no documented private disclosure route. We should decide internally whether we would report a future vulnerability publicly and accept the exposure window, or patch locally first.
• The new ## Support section and composer.json support key at least make the constraint explicit rather than implicit.

Scaling

• Checks run in the context of a save or an explicit Check action, so cost scales with editorial throughput rather than traffic. No bulk-scan throughput characteristics are documented.
• Panel rendering now routes every string through Vue's escaping. That is the correct default and removes the previous content-dependent render path; expect negligible cost difference.
• Findings lists on the Tools page scale with the number of failing checks per entry set; for large content libraries, confirm page behaviour before making it a daily-use screen.

Failure modes

• Fix applied in composer, not on disk: version reports 0.10.2 while the vulnerable bundle is still served. Highest-likelihood failure and the one to design against.
• Asset overwrite: --force clobbers any local customisation of the addon's published files.
• Silent styling regressions: the dropped list-disc class is the template — a class the panel's stylesheet does not contain renders flat with no error. Now guarded by a build test, but the class of failure persists for anything outside that test's coverage.
• False assurance: authors and auditors reading "accessibility gate" as "WCAG certified." Colour contrast is not checked. Keep the "Anything it finds" framing in our own documentation.
• Author confusion on refusal: previously a corner toast with the detail hidden on a collapsed-sidebar layout. Fixed, with a guard so builds lacking the reveal still draw the alert — but verify on our actual CP build.
• Dead UI affordance: the auto-placed field could be added as an entries-listing column that was always empty. Removed via listable: false.

Ramp-up

• Authors: one concept to learn — a refused save now takes them to the explanation. Low training cost, and the fix removes a genuine source of "it just says invalid" tickets.
• Admins and reviewers: must understand that findings are page-derived content rendered in their own panel, which is why the XSS mattered and why the upgrade is not optional. Brief whoever reviews gated entries.
• Platform/DevOps: the real ramp-up is the asset-publish discipline. One well-documented, verified pipeline step prevents the entire residual risk class from this release.
• Documentation quality improved meaningfully this cycle (install, support, corrected publish tag, corrected README claim about re-saving a stock home page). Onboarding effort for the next engineer is now materially lower than for 0.10.1.