Iam Laravel Package

Technical Evaluation

Architecture fit

• nextdeveloper/iam targets the Laravel ecosystem directly, so the expected shape is a Composer package with a service provider, publishable config, migrations, and middleware/gate hooks. That is idiomatic for Laravel and keeps the integration surface small: no sidecar, no external identity server, no new runtime.
• The v2.0.26 release materially changes the fit assessment. Shipping "admin endpoints to issue and revoke a user's QR sign-in badge" moves the package from a pure authorization data layer into the authentication path. That is a different category of dependency, with a different blast radius, and it contradicts the earlier working assumption that AuthN would remain with Sanctum/Passport and AuthZ would come from this package.
• The package's stated philosophy — "basic IAM kept as simple as possible, complexity is the developer's choice" — is now in tension with its own release history. QR badging is not a "basic IAM primitive"; it is a second authentication factor with credential issuance, lifecycle, and revocation semantics. Either the philosophy is aspirational marketing or the scope is drifting. Both readings argue for a narrower trust boundary than the release notes imply.
• Fit is strongest where the application already uses Laravel's native Gate/Policy and Auth abstractions and needs a persistence + admin layer for roles and permissions. Fit is now weakest on the authentication side: adopting the QR badge feature means adopting a home-grown second factor from a package with 3 stars and 0 dependents.
• Do not assume it replaces laravel/passport or laravel/sanctum. That was true before this release and is more true now: the package has added an authentication-adjacent capability without evidence it has replaced or integrated with the first-party token stacks. Confirm before designing around it.

Integration feasibility

• Base integration remains a standard composer require + php artisan vendor:publish + migrate flow. The QR badge feature adds migration surface (badge tables, secret/token storage), route registration for admin endpoints, and at least one new consumer-facing verification path. Installation stays under a day; verification does not.
• The material risk is still version compatibility opacity, now compounded by change-significance opacity. A feature of this size shipped as v2.0.26 — a patch bump — indicates the project does not follow SemVer for feature delivery. That means the version number carries no reliable signal about what will break, so we cannot triage upgrades by constraint alone; every release must be read.
• Signals in the supplied metadata warrant scrutiny before commitment:
  • Stars: 3, Dependents: 0 — effectively no production evidence anywhere in the ecosystem, and now with an authentication-adjacent feature that has had no external review.
  • Score: 19.65 against a typical 100-point maturity scale reads as low-confidence; treat it as a "do deep due diligence" flag, not a disqualifier.
  • Last release: 2026-10-05 is a future/anomalous date relative to a normal release cadence. Either the metadata is wrong, tags are being misused, or the release process is not conventional. Verify the actual git tags, changelog, and Packagist version history directly.
  • New: A patch-level feature release with no accompanying security note, migration guide, or threat-model discussion. For QR-based sign-in that is a documentation gap we must close ourselves.
• Licence is MIT, which removes legal friction and, importantly, preserves our right to fork. That materially lowers the downside of the adoption decision — and it is the reason the QR feature can be evaluated safely: we can read it, and if we dislike it, strip it.

Technical risk

• Bus factor. A single-maintainer package with negligible community is a continuity risk. The new feature increases the volume of code we would inherit on a fork, because a security-sensitive authentication path is now part of the inherited surface. Budget for that from day one.
• Security blast radius — escalated. IAM code sits on the critical path of every request; authentication code sits on the path of every login. A defect in permission resolution is a potential privilege escalation. A defect in QR badge issuance or revocation is a potential account takeover, and revocation bugs are worse than issuance bugs because they fail silently: the badge still works, and nobody knows.
• Unspecified threat model for the badge. The release notes describe endpoints, not cryptography. Unknown and decision-blocking: what the QR payload actually contains (opaque random token vs. signed assertion vs. embedded user identifier), whether the secret is high-entropy and server-generated, whether the badge is single-use or long-lived, whether verification is constant-time, whether revoked badges are checked on every use or only at issuance, and whether an issued badge is bound to a device, an IP, or nothing at all.
• Privilege boundary on the new admin endpoints. "Admin endpoints to issue and revoke" means the package is now exposing routes that grant authentication credentials. Those routes are themselves an authorization surface. If they are registered by the service provider unconditionally, or gated by a coarse check like "is admin," then the package has introduced a privilege-escalation path into apps that never asked for one. A compromised admin session can now mint standing credentials for any user.
• Abstraction leakage. "Make it as complicated as you want" often means the core is deliberately incomplete — admin UI, caching, tenant scoping, audit logging, and permission-inheritance semantics may all be ours to build. The release notes claim admin endpoints exist, which partially contradicts the earlier assumption of an absent admin surface, but "endpoints" is not "UI, audit trail, and revocation dashboard." Scope explicitly or the estimate will be wrong.
• Silent divergence from Laravel conventions. Still the core concern on the authorization side. On the new authentication side, the equivalent concern is divergence from Laravel's guard/session model: if a QR sign-in establishes a session outside Auth::login(), it will not participate in session regeneration, remember-me, or logout-everywhere, and it may not be picked up by existing middleware.

Key questions

1. Which Laravel and PHP versions are declared in composer.json, and is there a CI matrix that actually exercises them?
2. Does authorization flow through Laravel's Gate/Policy contracts, or does the package introduce its own check API?
3. What is the schema — roles, permissions, polymorphic assignments, teams/tenancy? Is it additive to users or does it expect to own the user model?
4. Is there a caching layer for permission lookups, and how is invalidation handled on role change?
5. Are there tests, and what is coverage on the authorization resolution path specifically?
6. What is the audit trail story — can we answer "who granted this role, when, and why"?
7. Is there a documented upgrade path between majors, or is the changelog a list of commits?
8. What does the maintainer's issue-response cadence look like over the last 12 months?
9. New: What is the QR badge payload — opaque token, signed assertion, or user identifier — and where is the secret stored?
10. New: Is badge verification a per-request check or a one-time exchange, and is revocation enforced on every subsequent use?
11. New: Are the admin issue/revoke routes opt-in (config-gated, not auto-registered), and what middleware protects them by default?
12. New: Does QR sign-in terminate in a standard Laravel Auth::login() session, or a parallel mechanism?
13. New: Does this release include migrations, and are they additive and reversible?
14. New: Is there any note on why a feature of this scope shipped as a patch version — is there an unreleased breaking change queued behind it?

Integration Approach

Stack fit

The package now spans two layers, and they should be adopted separately, not together. The authorization data layer is a low-regret adoption. The QR authentication feature is a separate decision with a separate risk profile and should not ride in on the same approval. Design the integration so the second is opt-in, not implied by the first.

Migration path

• If we are on ad-hoc role columns or hardcoded if ($user->is_admin) checks: this is a greenfield authorization model, and the package gives structure cheaply. Straightforward — and stop at the authorization layer for the initial rollout.
• If we are on spatie/laravel-permission: a swap is a data migration, not a code migration. Both packages model roles/permissions similarly on the surface but differ in pivot shape, guard handling, and caching. Expect a backfill script plus a parallel-run period. Do not attempt a cutover without both models live simultaneously behind a feature flag.
• If we are on hand-rolled gates with no persistence: the migration is mostly modelling work (enumerating permissions, mapping endpoints to abilities), which dwarfs the package installation effort. Budget accordingly — this is the true cost centre.
• QR path (new, and separate): do not migrate an existing MFA factor to this. If we have TOTP, WebAuthn, or SMS today, the QR badge is an additional option at best and a downgrade at worst. Treat adoption as additive and reversible: enable for an internal pilot cohort, keep the existing factor as the default, and require explicit per-user opt-in. There is no safe bulk-migration story for an authentication factor whose threat model we have not read.

Compatibility

• Wrap the package behind a thin internal interface (AuthorizationService) from the first commit. Every call site depends on our interface, never on the vendor namespace. This is the single highest-leverage decision in the whole integration: it makes a later swap to Spatie, Casbin, or an in-house implementation a one-file change, and it caps the vendor risk that the 3-star metric implies.
• Extend the same pattern to authentication. The QR feature must sit behind an internal BadgeAuthService with issue, revoke, and verify methods. Application code must never call a vendor badge route or model directly. This is what lets us disable the feature in one line if the threat model turns out to be unacceptable.
• Verify guard handling early if the app has multiple guards (web, API, admin). Multi-guard permission semantics are the most common source of subtle bugs in this category, and badge-issued sessions raise the same question.
• Verify the admin routes are not auto-registered in a way that exposes them on public hosts. Inspect route:list immediately after install, before deploying anywhere reachable.

Sequencing

1. Spike (3–5 days). Read the source end to end, with the QR path read first since it is the highest-risk addition. Install in a throwaway branch. Assert: does Gate::allows() honour package permissions? Do policies compose with them? What happens on cache clear? What does a badge payload contain, and what stops a replayed one?
2. Decision gate — split into two. (a) Authorization layer: score against build-vs-buy; if it saves fewer than ~10 engineering days versus a 300-line internal implementation, build it. (b) QR authentication: default to no. Adopt only if the threat model holds up under review and we have a concrete requirement the existing factor set does not meet.
3. Adapter layer. Define the internal interfaces — AuthorizationService and, only if (b) passed, BadgeAuthService — and implement over the package. No direct vendor references outside the adapters.
4. Shadow mode. Persist permissions but do not enforce. Log what would have been denied. Run for one to two weeks against real traffic to surface mapping gaps before they become outages. The QR feature stays disabled throughout this phase.
5. Enforce, progressively. Low-risk read-only surfaces first, then write operations, then admin and billing surfaces last. Feature-flag each step.
6. QR pilot, if approved at step 2b. Internal users only, secondary factor only, with the existing factor still available. Instrument issuance, verification, and revocation separately from day one.
7. Decommission the legacy checks and remove the flag only after a full release cycle at 100%.

Operational Impact

Maintenance

• Assume we are the maintainers. With 0 dependents, upstream fixes for our specific issues are not a realistic expectation. Budget a standing allocation — realistically 1–2 engineer-days per quarter for the authorization layer, plus additional allocation if we enable the QR feature, since authentication code carries a higher rate of security-driven patching.
• Upgrade discipline changes with this release. Because features ship as patch bumps, we cannot rely on ~2.0 to be safe. Pin to an exact version or commit SHA, diff every upgrade, and require a human read of the changelog before merging. Automating this package's updates is not appropriate.
• Fork contingency plan is mandatory, not optional. Mirror the repo internally, confirm MIT permits our use, and designate an owner for the fork. The fork should be exercised (a trivial patch applied) before we need it in anger. A plausible first use of that fork is removing the QR endpoints entirely.
• Track the package in the same SBOM/CVE pipeline as any other production dependency. The combination of low visibility and a newly added credential-issuing surface makes it a more attractive supply-chain target than it was at v1.

Support

• Internal support only. No vendor SLA, no commercial backing, no community forum to lean on. Escalation path is "the engineer who read the source." Mitigate by ensuring at least two engineers have read the authorization resolution path — and, if the QR feature is enabled, at least two have read the badge issue/verify/revoke path as well.
• Document the permission model in the repo's own ADR. Add a second ADR for the badge design if adopted, covering key rotation, revocation propagation, and the incident runbook for a suspected badge compromise.
• New runbook requirement: "revoke all badges for user X" and "rotate the badge signing secret" must both be executable procedures, tested, and not dependent on navigating an admin UI that may not exist.

Scaling

• Authorization checks occur on nearly every request; the performance question is whether permission resolution is cached and whether it is cached per-request or per-user-across-requests. Confirm and, if absent, add a request-scoped memoisation layer at the adapter — cheap and high-value.
• Watch for N+1 queries when loading a user's effective permissions across roles. This is the classic failure mode in role-based packages and it degrades gracefully at low traffic, then falls over at growth. Load-test with realistic role counts (a user with 5+ roles, 200+ permissions) before launch, not after.
• Badge verification is a new hot path if it is checked per request rather than per session. Establish which it is during the spike; a per-request database lookup on every authenticated call is a straightforward throughput regression that will not show up in a small test environment.
• Multi-tenancy is the scaling cliff. If tenant scoping is not native, every permission query needs a tenant predicate, and a missed predicate is a cross-tenant data exposure. The QR endpoints inherit this problem: a cross-tenant badge could authenticate a user into the wrong tenant. If multi-tenancy is on the roadmap, treat this as a build decision rather than a buy decision.

Failure modes

• Fail-closed is non-negotiable. Any exception in the authorization path must deny. Verify the package's behaviour under a database outage explicitly — do not assume. The same applies to badge verification: a verification that errors must reject, not fall back to the primary factor without logging.
• Instrument deny rates per route. A sudden step change is the fastest signal of a broken mapping or a stale cache, and it is the difference between a five-minute fix and an incident review. Add equivalent instrumentation for badge issue, verify, and revoke before enabling the feature, not after.
• New: alert on badge issuance volume per admin per hour. The endpoint is a credential factory; anomalous minting is the clearest signal of admin compromise.

Ramp-up

• Installation is hours; productive understanding is days. The learning curve is not the API (which is intentionally small) but the permission model we design on top of it — that is our artifact, and it needs an owner, a written taxonomy, and a review before it spreads across the codebase.
• The QR feature adds a second, steeper learning curve: reading an authentication path properly requires someone comfortable with credential lifecycle and replay analysis, not just Laravel conventions. If we do not have that person, that is itself the answer to question 2b.
• Onboarding cost is moderate and front-loaded: one focused read of the source plus the internal ADRs gets a capable Laravel engineer productive. The adapter layers are what keep that cost from compounding as the team grows — and they are what make the QR decision reversible.
• Recommendation: proceed to a time-boxed spike, not to adoption — and split the decision. The authorization data layer remains a low-regret experiment worth an adapter and a shadow-mode rollout. The QR sign-in feature, arriving in a patch release from a 3-star, 0-dependent package with no stated threat model, should be explicitly declined for now and revisited only if the source review answers questions 9–12 satisfactorily and a real requirement exists. The MIT licence and adapter-layer strategy keep both doors open; the adoption signal keeps neither door wide.