Jwt For Laravel Laravel Package

Product Decisions This Supports

• Service-to-service auth as a first-class product surface. The package already models machine identity (service-jwt guards, issuer allowlists, per-issuer secrets) as a sibling of user auth. 1.2.0 makes that surface testable, which is the gate for deciding whether to standardize internal service auth on this package rather than a bespoke middleware or an external IdP.
• Test velocity as a build-vs-buy input. Jwt::fake()->actingAsService($issuer, $claims, $audience) mints a real HS256 token signed the way that issuer signs it (own jwt.service.secrets entry, else shared secret) and addressed to this service. Previously teams hand-encoded tokens or fell back to a real issuer, so the "cost of the in-house alternative" was quietly a pile of test fixtures. That cost now goes to zero, which materially shifts the buy case.
• Multi-tenant / multi-issuer roadmap de-risking. Because a fake can now mint for a foreign issuer while the guard still rejects anything off jwt.service.issuers, you can write acceptance tests for the "an unexpected caller is refused" path. That's a security requirement you can demo to a customer or auditor without standing up a second real service.
• Test isolation as a release-gate question. forgetActing() restores anonymity after actingAs() / actingAsService(). Laravel's withoutToken() couldn't, because the fake re-attaches its bearer to any request lacking an Authorization header. This is the kind of gap that produces "works alone, fails in the suite" flakes — worth tracking as an engineering-health item, not a feature.
• Onboarding and evaluation cost. Service auth is usually where new engineers stall. A one-line fake turns "how do I test the webhook consumer?" from a half-day archaeology exercise into a code-review comment.
• Concrete decisions unlocked now: whether to adopt this package for machine auth in the next service; whether to keep hand-rolled token fixtures in existing suites or migrate them; whether to write negative-path (bad issuer, wrong audience) tests before the next security review.

When to Consider This Package

Adopt when:

• You have (or are about to have) Laravel services calling each other and you want issuer-allowlisted, audience-scoped service tokens without building the signing/verification layer yourself.
• Your test suite needs to exercise both sides: legitimate callers via actingAsService(), and rejected callers via a foreign or unlisted issuer.
• You already use Laravel's auth testing idioms (actingAs(), Jwt::fake()) and want service identity to feel the same to engineers.
• You need per-issuer secret rotation (jwt.service.secrets) rather than one global shared secret, and you want that exercised in tests.
• You value a documented failure mode over a custom one — the guard's behavior on an off-allowlist issuer is now observable in a test, not just in a README.

Look elsewhere when:

• Your service-to-service traffic is expected to standardize on OIDC/mTLS with an external IdP (Auth0, Keycloak, SPIFFE/SPIRE). This package's HS256 shared-secret model is a fine internal default but is not a substitute for asymmetric, centrally-rotated identity at scale.
• You need cross-language callers. A PHP-only signing/verification story means non-PHP services must reimplement the token format independently; consider whether the contract is documented well enough to be worth that.
• You're not on Laravel, or you're on an unsupported version — the value here is the framework integration, not the JWT primitives.
• Your security posture forbids shared symmetric secrets between services at all. The fallback-to-shared-secret behavior in actingAsService() mirrors production, which is honest, but it also means the shared secret is a real part of your trust model.
• You only need user auth. The service-jwt machinery is additive complexity you'd be paying for in config surface and review time.

Migration note: this is an additive minor (1.2.0). App-issued outbound tokens deliberately keep their own issuer — the change is scoped to the test fake — so no production behavior changes and no coordinated rollout is needed. Existing hand-rolled token fixtures can be replaced incrementally.

How to Pitch It (Stakeholders)

To executives: This release removes a recurring tax on our test suites. Testing anything that involves one service calling another used to mean hand-building fake auth tokens — brittle, easy to get subtly wrong, and a common source of flaky builds. Two new test helpers let engineers simulate a trusted calling service in one line, and just as importantly, simulate an untrusted one to prove we reject it. It's a small, additive change with no production impact, but it lowers the cost of the security tests we're already committed to and shortens the path for new engineers touching service auth.

To engineering: Jwt::fake()->actingAsService($issuer, $claims, $audience) mints a genuine HS256 token as that issuer would sign it — using the issuer's own jwt.service.secrets entry if one exists, otherwise the shared secret — and addressed to this service. The fake's issuer is no longer pinned to jwt.service.issuer, so you can mint for a foreign issuer in tests; the guard still enforces the jwt.service.issuers allowlist, which is exactly the asymmetry you want. Your app's outbound tokens are unchanged and keep their configured issuer. forgetActing() clears the fake identity for subsequent requests — necessary because withoutToken() doesn't work against this fake, since it re-attaches a bearer to any request without an Authorization header. Add forgetActing() to tearDown or between scenarios rather than relying on withoutToken().

To security/compliance: The release makes two previously untested paths testable: the positive case (a legitimate caller with correct issuer and audience) and the negative case (a caller with an issuer outside the allowlist is still rejected). It does not weaken the trust model — the allowlist check remains in the guard, and the shared-secret fallback in the fake mirrors production behavior rather than inventing a new bypass. Recommend we add regression tests for bad-issuer and wrong-audience rejection as part of adoption.