Bearer Laravel Package

Technical Evaluation

Package: ryangjchandler/bearer — a lightweight bearer-token authentication guard for Laravel (token issuance, hashed storage, middleware-protected routes), positioned as a minimal alternative to Sanctum/Passport.

Architecture fit

• Fits applications that expose a token-authenticated JSON API and want a thin, opinionated auth layer rather than a full OAuth2 or SPA-cookie stack.
• Does not fit if the roadmap includes first-party SPA session auth, OAuth2/OIDC flows, refresh-token rotation, or fine-grained scope hierarchies — Sanctum or Passport remain the better architectural anchor there.
• Small surface area is the appeal: one guard, one token model, one middleware. Low conceptual weight in the codebase, which is good for a TPM to reason about and bad if you need capabilities it deliberately omits.

Integration feasibility

• Well-trodden Laravel package pattern: composer require, publish config + migration, add the token trait to the User model, register the guard in config/auth.php, attach middleware to API routes.
• Realistic effort is measured in days for a first integration and 1–2 sprints to harden (token lifecycle policy, revocation, test coverage), not a multi-quarter workstream.
• No framework-forking or service-provider hackery implied; it plugs into the standard auth stack.

Technical risk

• Security-critical blast radius. This package owns the authentication boundary. Any defect, however small, is an incident rather than a bug ticket. Treat it as tier-1 dependency regardless of its size.
• Bus factor / maintainer concentration. Effectively single-maintainer. This release's only change is a community-submitted compatibility PR (via laravel-shift), which is a positive hygiene signal — the package is being kept alive — but also evidence that the contributor base is thin and compatibility work is automated rather than deeply bespoke.
• Compatibility claims vs. tested reality. A patch release declaring Laravel 13.x support is semver-safe and non-breaking by inspection, but "declared compatible" should be verified against the CI matrix and, ideally, our own smoke tests before we depend on it in production.
• Version drift. A patch bump that widens the framework constraint can silently change the resolved dependency graph on composer update. Lockfile discipline matters more here than with a leaf utility package.

Key questions for the maintainer / our own review

1. Does the illuminate/* constraint now permit a range (e.g. ^10|^11|^12|^13) or has support for older majors been dropped? This determines whether v2.1.1 is a drop-in or a forced upgrade.
2. Is Laravel 13 actually exercised in CI, or is the constraint widened optimistically?
3. Were any changes made to token hashing, token model, or guard registration as part of this bump? (Release notes say no; verify the diff.)
4. What is the security disclosure process and expected patch latency for a vulnerability?
5. Is there a named secondary maintainer or a documented succession plan?
6. What is the PHP version floor after this change, and does it match our runtime images?

Verdict: Low-risk, incremental update that removes an upcoming framework-upgrade blocker. Worth adopting, with the caveat that this dependency should carry an explicit owner and a pinned version.

Integration Approach

Stack fit

• Target stack: Laravel 10/11/12 today, Laravel 13 forward-looking. v2.1.1 is the version that keeps this package viable across that transition — this is the entire value of the release from a planning standpoint.
• Verify PHP floor compatibility against our base images before rollout; a Laravel 13 constraint often drags a PHP minor-version bump with it.

Migration path

• From v2.1.0 → v2.1.1: no code changes expected. Semver patch, single dependency-constraint change. Update, run the auth test suite, ship.
• From Sanctum → bearer (if ever considered): non-trivial. Token table shape, hashing, and ability semantics differ; existing issued tokens will not carry over without a migration script and a forced re-issue event. Treat as a separate, deliberate project — not a side effect of this bump.
• Greenfield: adopt at ^2.1.1 and skip the intermediate versions entirely.

Compatibility

• Pin the constraint to ^2.1.1 rather than a floating ^2.0, so the Laravel 13 support is guaranteed to be present in any resolved graph.
• Confirm the package's own constraint range covers our current Laravel major, not just 13 — a widened-but-narrowed range is the most common regression in these compatibility PRs.

Sequencing

1. Week 1 — Verify. Read the v2.1.1 diff; confirm constraint range, CI matrix, PHP floor. No production exposure.
2. Week 1 — Pin. Bump the constraint in a branch, regenerate the lockfile, run the full suite plus any auth-specific integration tests.
3. Week 2 — Stage. Deploy to staging; exercise login, token issuance, token revocation, expired-token, and malformed-token paths against the new lockfile.
4. Week 2–3 — Production. Standard canary rollout. Auth is a hard dependency for every API consumer, so roll back on any elevation in 401/403 rates.
5. Later — Forward-plan. Once Laravel 13 is on the roadmap, this package is no longer the blocker; sequence the framework upgrade independently.

Operational Impact

Maintenance

• Very low ongoing churn: the package is small and releases are infrequent. Expect a handful of patch releases per year, mostly compatibility bumps.
• The real maintenance cost is tracking, not changing. Assign a named owner and subscribe to releases — an unmonitored auth dependency is the failure mode, not a busy changelog.
• Budget roughly one engineer-day per framework major for validation.

Support

• Community-only, no vendor SLA. There is no one to escalate to during an incident.
• Mitigation: fork-and-patch readiness. The package is small enough that a competent Laravel engineer can vendor it or patch in place within hours. Confirm we have that capability on the team before adoption, not during an outage.

Scaling

• Per-request cost is a token lookup — a single indexed database read on the hot path of every authenticated call. Index the token column (or hash column) explicitly and verify the query plan.
• At high request volume this becomes a database read-amplification problem. Plan for a short-TTL cache of token→user resolution if throughput demands it, with an explicit revocation-invalidation strategy.
• Token table growth is the slow-burn issue: without expiry and cleanup, the table grows unbounded and lookup latency degrades. Define a retention/rotation policy at integration time, not after the first incident.

Failure modes

• Guard misconfiguration → blanket 401s across the API. Highest-probability, highest-visibility failure. Cover with a deploy-time smoke test.
• Dependency resolution drift → a routine composer update resolves a Laravel major we haven't validated. Lockfile discipline and CI on the resolved graph.
• Hashing/format change across versions → silent invalidation of every issued token, forcing a mass re-auth event.
• Stale revocation cache → revoked tokens remain valid for the cache TTL. Bound the TTL and document the exposure window.
• Maintainer abandonment → no patches for a future Laravel major or a disclosed vulnerability. Detect early via release-cadence monitoring; the fork path is viable given the package size.
• Unbounded token table → gradual latency creep and storage growth; not an outage, but a slow degradation that is easy to miss.

Ramp-up

• Low: a Laravel-fluent engineer is productive in half a day. The integration points (guard, trait, middleware) are idiomatic and require no package-specific knowledge.
• The non-obvious learning is operational, not technical: token lifecycle policy, revocation semantics, and the incident runbook for auth failures. Document those explicitly — they are not in the package's README and are the actual onboarding cost.
• Recommend a short internal design note (~1 page) covering token issuance, expiry, revocation, and the rollback procedure, so the team is not reverse-engineering auth behavior during an incident.

Recommendation: Adopt v2.1.1. It is a low-risk patch that clears the Laravel 13 blocker and buys forward compatibility at essentially zero integration cost. Gate the decision on confirming the constraint range still covers our current Laravel major, and treat the dependency as tier-1 with a named owner and fork readiness.