Make the route prefix configurable; move OAuth/SSO routes under it - #44
Merged
Merged
Conversation
New route_prefix config key (NEEV_ROUTE_PREFIX, default 'neev')
namespaces every machine-facing route the package registers — the API
namespace, web OAuth redirect/callback, tenant SSO, and /csrf-cookie.
Blade UI pages (/login, /account/...) stay at the root: they are
end-user URLs, not part of the API namespace. Route names are
unchanged, so nothing generated from names breaks.
Why a config value and not 'auth' or the status quo (per
docs/design-principles.md, layer 2):
- The prefix is one of the few package strings end users see (browser
URLs, links in verification/reset emails), and real apps differ on
it — the Sanctum ('sanctum.prefix') and Fortify ('fortify.prefix')
precedent
- Hardcoding 'auth' would break every consumer for zero functional
gain and collide with the most common app-owned route namespace
- 'Publish the routes file and edit it' was a trap: the MFA-token
route gate in NeevAPIMiddleware hardcoded 'neev/...' paths, so a
renamed prefix silently broke MFA step-up. The gate now follows the
configured prefix
BREAKING: /oauth/{service}[/callback] -> /neev/oauth/...,
/sso/redirect|callback -> /neev/sso/..., /api/tenant/auth ->
/neev/tenant/auth. Redirect URIs registered at identity providers
(Entra/Google/Okta, OAuth apps) must be updated; documented in
UPGRADING.md. The OAuth API controller's hand-built redirect URL now
derives from the prefix as well.
4 new tests prove a custom prefix end-to-end (login, authenticated
routes, the MFA route gate, SSO/csrf-cookie). Suite 995 green; Pint
and PHPStan clean; all docs updated to the prefixed paths.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Codecov ReportCaution This repository is currently using the Sentry GitHub App to receive Codecov PR comments. This integration will be deprecated on July 8, 2026. Please install the Codecov GitHub App to continue receiving coverage reports on your pull requests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
route_prefix(NEEV_ROUTE_PREFIX, defaultneev) — one knob that namespaces every machine-facing route the package registers: the API namespace, web OAuth redirect/callback, tenant SSO, and/csrf-cookie. Blade UI pages (/login,/account/...) deliberately stay at the root — they're end-user page URLs, not API namespace. Route names are unchanged, so email links androute()calls are unaffected by a rename.Setting
NEEV_ROUTE_PREFIX=authgives/auth/login,/auth/oauth/{service}/callback,/auth/sso/callback, etc.Why this option (per
docs/design-principles.md, layer 2)sanctum.prefix) and Fortify (fortify.prefix) both made exactly this call.auth: breaking for every consumer for zero functional gain, andauthis the most collision-prone namespace an app owns.routes/neev.php, edit the prefix) was a trap —NeevAPIMiddlewarehardcodedneev/mfa/...in the MFA-token route gate, so a renamed prefix silently broke MFA step-up. The gate now follows the configured prefix.BREAKING — identity provider action required
Per Sam's call, everything machine-facing binds to the prefix, which moves three route groups:
/oauth/{service}[/callback](web)/neev/oauth/{service}[/callback]/sso/redirect,/sso/callback/neev/sso/redirect,/neev/sso/callback/api/tenant/auth/neev/tenant/authRedirect URIs registered at identity providers (Entra/Google/Okta app registrations, OAuth apps) must be updated — documented with the full table in UPGRADING.md. The OAuth API controller's hand-built redirect URL now derives from the prefix too.
Testing
New
CustomRoutePrefixTestboots the app withroute_prefix=authand proves: login under/auth/*(and 404 under/neev/*), authenticated API routes, the MFA-token route gate following the prefix, and SSO/csrf-cookie placement. Suite 995 green; Pint and PHPStan clean. Docs updated across api-reference, web-routes, multi-tenancy, authentication, installation, configuration, README, and the design-principles applied-decisions table.