fastify-auth-and-oauth

Fastify Auth And OAuth

Use this skill for Fastify services that need local auth boundaries or OAuth-based login and token validation.

Scope

• authorization code flow with PKCE
• login and callback route design
• session and cookie boundaries for browser-based auth
• access token and refresh token handling
• JWT claim validation and protected routes
• redirect URI, state, scope, and issuer or audience validation
• Fastify hooks and plugins that enforce auth consistently

Default path

1. Confirm whether the app is a browser-facing OAuth client, an API validating tokens, or both.
2. Prefer authorization code with PKCE for user login flows.
3. Keep the callback route focused on exchanging the code, validating state, and creating the local session boundary.
4. Store only the minimum token material needed for the app flow.
5. Validate token claims at the API boundary:
   • expiration
   • issuer
   • audience
   • subject when relevant
6. Rotate refresh tokens consistently if the provider uses rotation semantics.
7. Protect routes with a shared hook or middleware boundary instead of duplicating token checks per handler.

When to deviate

• Use API-only token validation flows when the service is not doing browser login.
• Prefer local session boundaries when the app is browser-facing and token secrecy matters.
• Move to general Fastify best practices when the real problem is plugin or lifecycle architecture rather than auth flow design.

Guardrails

• Do not use implicit flow for new browser-based work.
• Do not skip PKCE for public clients.
• Do not accept arbitrary redirect URIs.
• Do not log raw access tokens or refresh tokens.
• Do not treat signature verification as enough if issuer or audience checks are missing.
• Prefer secure, HttpOnly cookie-backed session boundaries over browser storage for sensitive token material.

Avoid

• using implicit flow for new browser-based work
• skipping PKCE on public clients
• accepting open redirect-uri behavior
• validating JWT signatures without issuer or audience checks
• scattering auth checks across handlers