0.9.0

AssegaiPHP Auth 0.9.0

0.9.0 aligns assegaiphp/auth with the AssegaiPHP 0.9 release line and hardens the package’s authentication flows in a few important security-sensitive places.

This release keeps the package intentionally focused: small authentication strategies for AssegaiPHP and standalone PHP applications, without turning the package into a full auth framework.

Highlights

PHP 8.4 baseline

assegaiphp/auth now requires PHP >=8.4.

The package stays lightweight and continues to depend only on:

• firebase/php-jwt
• assegaiphp/attributes

Session authentication hardening

SessionAuthStrategy now rotates the session ID when establishing an authenticated user.

That applies to both:

• normal username/password authentication
• trusted handoff flows such as OAuth callback sign-in

This closes a session-fixation weakness where a user could authenticate into a previously known session identifier.

The strategy still keeps its earlier safe behavior of:

• starting a session when needed
• cloning the configured user object
• stripping the password field before storing the user in session

JWT issuer and audience enforcement

JwtAuthStrategy now enforces configured issuer and audience claims during authentication checks.

Before this change, the strategy could mint tokens with iss and aud but did not consistently reject validly signed tokens whose issuer or audience did not match the configured service boundary.

0.9.0 tightens that behavior so isAuthenticated() now checks:

• signature and decode validity
• configured issuer matches iss
• configured audience matches aud

Audience matching also supports the common cases of either:

• a single string audience
• an array audience claim

This makes JWT trust boundaries more explicit and safer when secrets are shared across services or environments.

OAuth 2.0 callback fixes

OAuth2AuthStrategy now correctly supports valid non-PKCE authorization-code flows.

Previously, the callback path treated a missing stored verifier as an invalid state even when PKCE was intentionally disabled. That made usePkce: false effectively non-functional.

This release fixes that behavior by allowing valid state-only callbacks when PKCE is disabled, while still rejecting genuinely invalid or expired state.

OAuth state store behavior clarified

SessionOAuthStateStore now preserves a distinct “valid non-PKCE state” sentinel instead of collapsing it into the same result as an invalid state.

That allows the OAuth strategy to tell the difference between:

• a valid stored state with no PKCE verifier
• a missing or invalid state

The stored state remains one-time-use and is still consumed on callback.

Repository health and release-line alignment

0.9.0 also brings the package in line with the wider AssegaiPHP release process.

That includes:

• refreshed README package positioning
• repo-health metadata updates
• contribution workflow documentation
• pre-push quality gate setup
• CI alignment for the current package state

What did not change

This release does not turn assegaiphp/auth into a full auth system.

It still does not provide:

• user persistence
• registration flows
• password reset flows
• refresh token rotation
• generated OAuth controllers/routes
• a large provider catalog beyond the shipped GitHub adapter

You still own the surrounding application flow: user lookup, route wiring, post-login behavior, and account lifecycle.

Behavior changes to note

The most important runtime changes are:

• session-backed login now regenerates the session ID
• JWT validation now rejects issuer and audience mismatches
• non-PKCE OAuth callbacks now work when the state is valid

If you had tests or application code that accidentally relied on the older, looser JWT validation behavior, update those expectations now.

Upgrade notes

If you are upgrading from 0.6.3:

• PHP 8.4 or newer is now required.
• No namespace changes are required.
• Existing session and JWT strategy usage should keep working.
• If you configure issuer and audience on JWT strategies, tokens must now actually match those values during authentication.
• If you use OAuth with usePkce: false, that flow now behaves correctly instead of being rejected as invalid state.

Verification

Tested with:

composer test

The release also includes expanded unit coverage for:

• session ID regeneration
• JWT issuer validation
• JWT audience validation
• valid non-PKCE OAuth callbacks
• session-backed OAuth state consumption

What comes next

The next steps toward 1.0 should focus on:

• additional OAuth provider adapters
• clearer framework integration seams for guards and route wiring
• optional refresh-token and rotation patterns
• stronger documentation around recommended production auth architecture

Full Changelog: 0.6.3...0.9.0