Skip to main content

Auth, Routing, and Middleware Feature Context

Source: .agents/references/features/auth-routing-and-middleware.md

Content​

Auth, Routing, and Middleware Feature Context

Purpose​

Auth, routing, and middleware protect route access, locale/country redirects, portal path redirects, Flutter/webview behavior, token refresh, login/logout/reset flows, and public/private page boundaries. This domain is high-impact because incorrect redirects can break SEO, checkout, community access, or authenticated creator/member workflows.

User-Facing Workflows​

  • Visitors and members move through login, logout, OAuth, reset/forget password, email redirect, and account deletion flows.
  • Requests pass through middleware that may redirect based on country, locale, community page rules, portal path, product checkout path, authenticated user state, or Flutter/webview context.
  • Authenticated-only pages should redirect unauthenticated users without breaking public community pages.
  • Public routes must remain accessible unless a middleware explicitly gates them.

Key Entrypoints​

  • Routes:
    • src/middleware.page.js
    • src/pages/auth/
    • src/pages/login/
    • src/pages/logout/
    • src/pages/oauth/
    • src/pages/forget-password/
    • src/pages/reset-password/
    • src/pages/email-redirect/
    • src/pages/account-deletion/
    • src/pages/reroute-user/
  • Middleware:
    • src/middlewares/withMiddlewares.ts
    • src/middlewares/authenticatedUserRedirectionMiddleware.ts
    • src/middlewares/communityPageRedirectionMiddleware.ts
    • src/middlewares/communityPageMemberRedirectionMiddleware.ts
    • src/middlewares/communityCookieRemovalMiddleware.ts
    • src/middlewares/commonLocaleRedirectionMiddleware.ts
    • src/middlewares/countryPricingRedirectionMiddleware.ts
    • src/middlewares/countryZerolinkRedirectionMiddleware.ts
    • src/middlewares/domainSwitchMiddleware.ts
    • src/middlewares/portalRedirectionMiddleware.ts
    • src/middlewares/portalSettingsPathMiddleware.ts
    • src/middlewares/portalMoneyPathMiddleware.ts
    • src/middlewares/appCheckoutRedirectionMiddleware.ts
    • src/middlewares/flutterWebMiddleware/
  • Modules/hooks/utilities:
    • src/modules/Auth.js
    • src/hooks/router/useParametrizedPathname.ts
    • src/hooks/router/useShallowRouterReplace.ts
    • src/utility/jwtHelper.ts
    • src/utility/cookieService.ts
    • src/utility/loginConstants.js
    • src/utility/webview.js
    • src/utility/middleware/
  • Services:
    • src/services/userService.js
    • src/services/helpers/authorizedRequest.js
    • src/services/helpers/adminProtectedAxiosRequest.ts
    • src/services/helpers/staticServerProtectedAxiosRequest.js

Data Flow and Service Boundaries​

  • Middleware ordering matters. Inspect withMiddlewares.ts and src/middleware.page.js before adding or changing a redirect rule.
  • Redirect logic often depends on cookies, country/locale, community slugs, portal paths, and auth state. Preserve existing fallback behavior for missing or malformed values.
  • Auth token helpers and request helpers may run in server or browser contexts. Do not assume window or document is available.
  • Service helper changes can affect all API calls. Keep helper edits narrow and run broad verification when touching request/authorization utilities.
  • Route changes should consider Next.js page naming conventions: page files use .page.js or .page.tsx.

Conventions and Gotchas​

  • Treat query params, slugs, cookies, and JWTs as untrusted. Validate and narrow before use.
  • Do not store sensitive credentials in direct browser storage. Use existing cookie/request helpers.
  • Avoid direct window or document access outside guarded browser-only code.
  • Redirect bugs often show up as loops. Check both the source route and target route when changing middleware.
  • Preserve locale and country pricing behavior unless the task explicitly changes routing policy.
  • Middleware code may be TypeScript while some route/auth modules are JavaScript. Keep existing extension unless migrating is requested.
  • .agents/rules/web-security.mdc
  • .agents/rules/prefer-typescript-files.mdc
  • .agents/rules/clean-typescript.mdc
  • .agents/rules/bun-first.mdc
  • .agents/references/features/community-public-pages.md
  • .agents/references/features/checkout-and-payments.md

Useful Searches​

rtk rg "redirect|middleware|cookie|jwt|authorizedRequest|login|logout|oauth|webview" src/middleware.page.js src/middlewares src/pages src/utility src/services
rtk find src/middlewares -maxdepth 3 -type f
rtk rg "router.replace|router.push|useShallowRouterReplace|useParametrizedPathname" src

Update Triggers​

Update this reference when middleware order, redirect policy, auth helper contracts, login/reset routes, or server/client request helper behavior changes.