PluginMind Docs

Authentication

PluginMind uses a dual-stage authentication flow that keeps tokens server-side while giving the backend full control over sessions.

🧭 Overview

  1. NextAuth (frontend) handles Google OAuth using the App Router runtime.
  2. The custom proxy at src/app/api/proxy/[...path]/route.ts extracts the Google ID token and forwards it to the backend exactly once.
  3. FastAPI validates the token via Google, creates a signed pm_session cookie, and returns it to the browser.
  4. All subsequent requests rely on the pm_session cookie—no access tokens are exposed to client-side code.
Rendering diagram…

🛠️ Backend Endpoints

EndpointMethodDescription
/auth/googlePOSTValidates Google ID token and issues pm_session. Requires body { "id_token": "..." }.
/auth/logoutPOSTClears the session cookie using get_logout_cookie_settings().
/auth/validateGETLegacy helper returning { valid: true } for valid bearer tokens.
/auth/meGETReturns the authenticated user using the session cookie (structured for the Next.js frontend).

All endpoints pull the session via get_session_user or get_session_payload (app/middleware/session_auth.py).

🍪 Session Cookie Details

Loading code snippet…

Good to know

  • Sessions last 24 hours by default.
  • Set SESSION_COOKIE_DOMAIN to share cookies across subdomains.
  • BACKEND_SESSION_SECRET must be at least 32 characters.

🧾 Request Examples

Bind (one-time)

Loading code snippet…

Authenticated API call

Loading code snippet…

🧪 Testing & Mocks

  • Backend tests use create_session_token to set cookies directly (tests/test_generic_processing.py).
  • JWT unit tests mock Google verification so they do not hit the network (tests/test_jwt_security.py).
  • CI runs TESTING=1 pytest, which automatically provisions safe dummy environment variables (tests/conftest.py).

🧱 Hardening Tips

  • Always call backend APIs with credentials: 'include' in fetch/axios.
  • Rotate BACKEND_SESSION_SECRET if you suspect token leakage.
  • Configure NEXT_PUBLIC_SECURE_TOKENS=true to prevent NextAuth from exposing provider tokens in the browser.
  • For local development over HTTP, leave secure=False; for production, set ENVIRONMENT=production so cookies ride HTTPS only.

Stay safe and session-based! 🛡️