Fuse Utilities Laravel Package

Technical Evaluation

Architecture fit mitydigital/fuse-utilities is a Laravel companion package for the Fuse CMS family — a helper/utility layer that plugs in via package auto-discovery, published config, and Blade/helper surfaces. Historically its scope has been presentational and convenience-oriented (public asset handling, formatting utilities). Release 6.2.0 (Add support for private assets, PR #23) is the first signal of a scope expansion into access-controlled asset delivery, which is a materially different architectural concern: it implies filesystem disk abstraction, route/controller involvement, and some authorization or URL-signing model. For a TPM this matters because the package stops being purely "render helper" and becomes security-adjacent surface area that belongs in the threat model and the access-control review, not just the front-end toolkit.

Integration feasibility Low-to-moderate. The version delta is 6.1.0 → 6.2.0, a semver minor bump, so on conventional semver reading this is additive and non-breaking. A composer update mitydigital/fuse-utilities should be the only mandatory step; the real work is configuration (a private disk in config/filesystems.php, likely a publishable config stub) and a decision about which content models are allowed to hold private assets. Feasibility is high for teams already running Fuse with a standard Laravel filesystem setup, and lower where assets are currently assumed to be public-by-default throughout templates and content.

Technical risk

• Confidentiality risk is the headline. Private asset support means a misconfiguration can expose files that were intended to be restricted. The classic failure is a private disk symlinked or configured under public/, or a cached/signed URL outliving its authorization.
• Ambiguous feature contract. The release note is one line. We do not know whether "private assets" means (a) storage on a non-public disk with app-mediated delivery, (b) signed/temporary URLs, (c) per-model visibility flags, or (d) all of the above. Scope must be confirmed before we commit to a design.
• Static-generation tension. If the Fuse stack produces statically exported output, private assets are conceptually in conflict with it and will need a hybrid serving path. This is the single largest unknown for architecture.
• CDN/caching incompatibility. Authorized, per-user asset responses generally must not be cached at the edge; existing cache and CDN rules may need explicit exclusions.
• Test coverage and security review. A one-line changelog gives no visibility into negative-path testing (unauthorized request, expired URL, wrong disk). Treat as unvetted until reviewed.

Key questions

1. What precisely does "private assets" implement — disk selection, signed URLs, policy/authorization hooks, or middleware-gated routes?
2. Does 6.2.0 register new routes or middleware, and are they opt-in or automatic?
3. Which Laravel, PHP, and Fuse core versions are supported, and is there a documented upgrade note for 6.1.x users?
4. Are there new config keys or a publishable config file, and are defaults safe (i.e., deny-by-default)?
5. How does this behave under static export, if that mode is supported?
6. What is the package's maintenance posture — release cadence, security disclosure process, test suite visibility?

Integration Approach

Stack fit Fits cleanly into a standard Laravel application: Composer install, service provider auto-discovery, optional config publish, and a private disk declared in config/filesystems.php (local storage/app/private or an S3-compatible bucket). S3 with pre-signed URLs is the cleanest fit because it moves byte-serving off the PHP fleet and gives us native expiry semantics. Local-disk delivery is fine for lower traffic but routes file bytes through PHP-FPM.

Migration path

• Phase 0 (evaluation): pin the package in a scratch branch, read the diff for PR #23, and confirm the answers to the questions above. Do not ship to production on the changelog alone.
• Phase 1 (upgrade only): bump 6.1.0 → 6.2.0 with no behavior change. This is a safe, reversible step that validates compatibility across the existing test suite.
• Phase 2 (enablement): publish any new config, create the private disk, wire storage permissions, and enable private assets for a single low-risk content type.
• Phase 3 (content migration, optional): moving existing public assets to private is a separate, larger project — inventory files, relocate, rewrite content references, and backfill redirects. Defer this unless there is a concrete confidentiality driver; it is not required to adopt 6.2.0.

Compatibility Validate against: our Laravel/PHP version matrix, the Fuse core version in use, other Fuse add-ons that touch the asset pipeline, our image-conversion/queue tooling, and CDN cache rules. The main compatibility unknowns are Fuse core version coupling and any overlap with packages that already wrap asset URL generation.

Sequencing Dev → automated test suite (including negative authorization cases we write ourselves) → staging with a production-like disk (S3, not local) → auth-matrix manual QA across roles and guest → single content type in production behind a config flag → wider rollout. Keep the Composer bump in its own PR, separate from any config or content changes, so rollback is a one-line revert.

Operational Impact

Maintenance Low ongoing effort for the version bump itself. The elevated ongoing cost is patch vigilance: once a package participates in access control, we should track it in our dependency advisory process and be prepared to take security patches quickly rather than on a routine quarterly cadence. Budget roughly a day for the upgrade and a few days for enablement, evaluation, and QA on the first content type.

Support Expect a new class of support ticket: "asset won't load" / "file is missing." First-line triage becomes a short checklist — is the user authorized, has the signed URL expired, is the disk configured and mounted, did the deployment create the storage link. This needs a written runbook before rollout, plus a documented permission matrix so support can answer "who should be able to see this file" without escalation.

Scaling Private delivery is inherently less cacheable than public delivery. Prefer S3 pre-signed URLs over app-mediated streaming so the PHP fleet is not in the byte path. Watch: signed-URL expiry tuned against real session lengths, image-conversion queues for private derivatives, opcache and worker sizing if streaming locally, and egress cost if assets are large or frequently accessed. Public assets remain on the CDN; only the private subset moves.

Failure modes

• Silent exposure — private disk misconfigured as public, or a CDN/cache rule caching an authorized response and serving it to others. Highest severity; mitigate with config review, cache-header assertions in tests, and a periodic automated check that the private path is not web-reachable.
• Broken assets — expired URLs, missing storage symlink after a fresh deploy, disk credentials rotated without config update.
• Backup/restore gaps — the private bucket or directory is excluded from backups or IaC, so restores silently lose restricted files.
• Static-export divergence — private assets referenced in statically generated pages that cannot resolve them.
• Version drift — staying on 6.1.x while the ecosystem moves; acceptable short-term, but re-evaluate at each Fuse core upgrade.

Ramp-up Developers familiar with Laravel's filesystem and Flysystem need little more than a walkthrough of the new config and the authorization path — call it half a day. Content editors and support staff need real training, because "this asset is private" is a content-authoring decision with confidentiality consequences; that is where the ramp-up cost and the incident risk actually sit. Deliverables before production enablement: an internal one-pager on the feature contract, a runbook for the failure modes above, and a named owner for the package.

Assessment basis: release notes for 6.2.0 only (single PR, one-line description). Confidence is low on feature semantics and moderate on integration mechanics. Re-rate after reviewing the PR diff, README changes, and test coverage.