auth-setup

name	auth-setup
description	Setting up authentication with guards, sessions, registration, password reset, gates/policies, and vendor views in Rudder
license	MIT
appliesTo	["@rudderjs/auth"]
trigger	configuring guards/providers in `config/auth.ts`, vendoring auth views, wiring `Gate`/`Policy`, or working with password reset / email verification
skip	a route handler that just reads `Auth.user()` — no setup needed
metadata	{"author":"rudderjs"}

Auth Setup

When to use this skill

Load when you're configuring guards/providers, vendoring auth views, wiring Gate/Policy authorization, or working with password reset / email verification. For depth, open the rule file matching your task.

Quick Reference

Task	Open
Provider setup — install deps, config/auth.ts, register provider, make User authenticatable	rules/provider-setup.md
Reading the current user — auth(), Auth facade, RequireAuth / RequireGuest middleware, login/logout endpoints	rules/guards-and-handlers.md
Login / register UI — vendor:publish auth views, registerAuthRoutes, custom paths and view ids	rules/auth-views.md
Authorization — Gate.define, model Policy classes, before callbacks	rules/gates-and-policies.md
Email verification + password reset — MustVerifyEmail, verificationUrl, PasswordBroker	rules/email-and-password-reset.md

Key concepts (load once)

• AuthManager — process-wide DI singleton that creates fresh SessionGuard instances per call. Never cached — cached guards leak _user across requests.
• auth() helper — Laravel-style accessor returning the request-scoped AuthManager via AsyncLocalStorage.
• Auth facade — Auth.user(), Auth.check(), etc. — static class that proxies to currentAuth().
• Middleware groups — AuthMiddleware auto-installs on the web group only. API routes are stateless by default; use RequireBearer() + scope(...) (passport) for token auth per-route.
• SessionGuard.user() soft-fails — returns null (not throw) when there's no ALS context, matching Laravel's Auth::user() semantics.
• Peer deps: @rudderjs/session and @rudderjs/hash are required peers. HashProvider must boot before AuthProvider (defaultProviders() orders this automatically).

Examples

See playground/config/auth.ts, playground/app/Models/User.ts, playground/routes/web.ts, and playground/app/Views/Auth/.