Auth Provider

Phase 2: Ecosystem-Specific Hard Constraints (Delegation Rules)

Stack: Next.js + Clerk

[!IMPORTANT] Domain Constraints (auth-provider)

1. Wrap the root layout in <ClerkProvider>. Protect all secure routes at the edge using clerkMiddleware.
2. Server components must fetch user state strictly via auth() and currentUser() from @clerk/nextjs/server.
3. Sub-agents must sync the backend Database users via a user.created Webhook sent from Clerk. Use svix to cryptographically verify this webhook signature.

Stack: Node / Fastify / Express (General Backend Validation)

[!IMPORTANT] Domain Constraints (auth-provider backend)

1. Sub-agents must validate the JWKS (JSON Web Key Set) issued by the Auth Provider using jwks-rsa and jsonwebtoken. Do not blindly trust unverified tokens from the client.
2. Implement a global requireAuth middleware that attaches the verified user payload to the request object.

Stack: Python / FastAPI (General Backend Validation)

[!IMPORTANT] Domain Constraints (auth-provider backend)

1. Sub-agents must validate the JWKS via python-jose and fetch keys securely using httpx. Cache the keys to prevent rate limiting.
2. Use FastAPI security.HTTPBearer() to define the auth dependency and inject the user object into routes.

Phase 3: Security Best Practices (Non-Negotiable)

1. Token Storage & Transmission

• Client-Side: Never store sensitive JWTs or access tokens in localStorage or sessionStorage if they are susceptible to XSS. Prefer HttpOnly cookies with Secure; SameSite=Strict flags.
• Transmission: All auth-related traffic MUST occur over HTTPS. Redirect HTTP to HTTPS at the infrastructure layer (Setup skill).

2. Session Management

• Expiry: Access tokens should have short expiry (e.g., 15-60 mins). Use Refresh tokens (stored securely) to obtain new access tokens.
• Revocation: Managed providers (Clerk, Supabase) handle revocation natively. For custom implementations, use a blocklist (Redis) to invalidate suspect tokens immediately.

3. Redirection Safety

• Allowlists: When implementing OAuth or email login, strictly validate the redirect_url against a predefined allowlist to prevent Open Redirect attacks.

Common Pitfalls

• Implicit Grant Flow: Abandoned and insecure. Always use Authorization Code Flow with PKCE for public clients (Mobile/React).
• Hardcoded Secrets: Never commit JWT secrets to version control. They MUST be in .env and rotated annually.
• Over-Scoping: Only request the minimal scopes needed for the feature (Principle of Least Privilege).