@rudderjs/auth 5.0.1 → 5.1.1

package/README.md

@@ -15,31 +15,13 @@ pnpm add @rudderjs/auth @rudderjs/hash @rudderjs/session
 import { User } from '../app/Models/User.js'
 
 export default {
-  defaults: {
-    guard: 'web',
-  },
-  guards: {
-    web: { driver: 'session', provider: 'users' },
-  },
-  providers: {
-    users: { driver: 'eloquent', model: User },
-  },
+  defaults: { guard: 'web' },
+  guards:   { web: { driver: 'session', provider: 'users' } },
+  providers:{ users: { driver: 'eloquent', model: User } },
 }
-
-// bootstrap/providers.ts
-import { SessionProvider } from '@rudderjs/session'
-import { HashProvider } from '@rudderjs/hash'
-import { AuthProvider } from '@rudderjs/auth'
-
-export default [
-  SessionProvider,
-  HashProvider,
-  AuthProvider,
-]
 ```
 
-> `AuthProvider` is the service-provider class — list it directly in the providers array.
-> `auth()` (lowercase) is the per-request helper — see below.
+`AuthProvider`, `SessionProvider`, and `HashProvider` are picked up by [auto-discovery](https://github.com/rudderjs/rudder/blob/main/docs/guide/service-providers.md#auto-discovery) — `pnpm rudder providers:discover` (or `--install` during scaffold) is all that's needed.
 
 ## Usage
 
@@ -70,6 +52,27 @@ Route.get('/profile', async (req) => {
 matched by `withRouting({ web })` has the auth context populated before your
 handler runs.
 
+### Reading the user from a view
+
+When `@rudderjs/vite` is installed, `AuthProvider.boot()` also registers a
+page-context enhancer that exposes the current user on `pageContext.user` —
+controller views (and any Vike page) can read it directly without a
+`+data.ts` or controller plumbing:
+
+```tsx
+// app/Views/Dashboard.tsx
+import { usePageContext } from 'vike-react/usePageContext'
+
+export default function Dashboard() {
+  const { user } = usePageContext()  // typed via Vike.PageContext augmentation
+  return <h1>Hello {user?.name ?? 'guest'}</h1>
+}
+```
+
+`pageContext.user` is `null` for guests. The registration is lazy and silently
+no-ops when `@rudderjs/vite` isn't installed, so the package stays usable
+standalone.
+
 **API routes stay stateless.** `AuthMiddleware` does not run on the `api` group
 by default — `req.user` will be `undefined`, and `Auth.user()` returns `null`.
 For token-based API auth, reach for [`@rudderjs/passport`](../passport):

package/boost/skills/auth-setup/SKILL.md

@@ -1,273 +1,40 @@
 ---
 name: auth-setup
 description: Setting up authentication with guards, sessions, registration, password reset, gates/policies, and vendor views in RudderJS
+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 this skill when you need to set up authentication, configure guards, add login/register views, implement authorization gates/policies, or work with password reset and email verification.
+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.
 
-## Key concepts
+## Quick Reference
 
-- **AuthManager**: Process-wide DI singleton that creates fresh `SessionGuard` instances per call (never cached -- prevents ghost user leaks across requests).
-- **Guard contract**: `user()`, `check()`, `guest()`, `attempt()`, `login()`, `logout()` -- all async.
-- **`auth()` helper**: Returns the current request's `AuthManager` via AsyncLocalStorage. Mirrors Laravel's `auth()->user()`.
-- **Auth facade**: `Auth.user()`, `Auth.check()` etc. -- static class that proxies to `currentAuth()`.
-- **AuthMiddleware**: Sets up the auth ALS context and populates `req.user` for every request.
-- **RequireAuth**: Returns 401 if not authenticated.
-- **RequireGuest**: Redirects authenticated users away from guest-only pages (login, register).
-- **Gate/Policy**: Authorization system for checking abilities and model-level policies.
+| 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` |
 
-## Step-by-step
+## Key concepts (load once)
 
-### 1. Install dependencies
-
-Auth requires `@rudderjs/session` and `@rudderjs/hash` as peer dependencies:
-
-```bash
-pnpm add @rudderjs/auth @rudderjs/session @rudderjs/hash
-```
-
-### 2. Configure auth (config/auth.ts)
-
-```ts
-import { User } from '../app/Models/User.js'
-import type { AuthConfig } from '@rudderjs/auth'
-
-export default {
-  defaults: {
-    guard: 'web',
-  },
-  guards: {
-    web: {
-      driver: 'session',
-      provider: 'users',
-    },
-  },
-  providers: {
-    users: {
-      driver: 'eloquent',
-      model: User,
-    },
-  },
-} satisfies AuthConfig
-```
-
-### 3. Register the provider (bootstrap/providers.ts)
-
-```ts
-import { defaultProviders } from '@rudderjs/core'
-// AuthProvider is auto-discovered via defaultProviders() if @rudderjs/auth is installed.
-// It requires HashProvider and SessionProvider to boot before it.
-export default [
-  ...(await defaultProviders()),
-  // ... your app providers
-]
-```
-
-### 4. Make the User model authenticatable
-
-```ts
-import { Model, Hidden } from '@rudderjs/orm'
-import type { Authenticatable } from '@rudderjs/auth'
-
-export class User extends Model implements Authenticatable {
-  static fillable = ['name', 'email', 'password']
-
-  @Hidden password = ''
-
-  getAuthIdentifier(): string { return String(this.id) }
-  getAuthPassword(): string { return this.password }
-  getRememberToken(): string | null { return null }
-  setRememberToken(_token: string): void {}
-}
-```
-
-### 5. Use auth in route handlers
-
-```ts
-import { auth, Auth, RequireAuth } from '@rudderjs/auth'
-
-// Using the auth() helper (Laravel-style)
-router.get('/api/me', async (req, res) => {
-  const user = await auth().user()
-  if (!user) return res.status(401).json({ message: 'Unauthorized' })
-  res.json({ user })
-})
-
-// Using the Auth facade
-router.get('/api/profile', async (req, res) => {
-  if (await Auth.guest()) return res.status(401).json({ message: 'Unauthorized' })
-  const user = await Auth.user()
-  res.json({ user })
-})
-
-// Using RequireAuth middleware
-router.get('/api/dashboard', RequireAuth(), async (req, res) => {
-  // req.user is guaranteed to exist here
-  res.json({ user: req.user })
-})
-```
-
-### 6. Login / logout endpoints
-
-```ts
-router.post('/auth/login', async (req, res) => {
-  const { email, password } = req.body
-  const success = await auth().attempt({ email, password })
-  if (!success) {
-    return res.status(422).json({ message: 'Invalid credentials.' })
-  }
-  const user = await auth().user()
-  res.json({ user })
-})
-
-router.post('/auth/register', async (req, res) => {
-  const user = await User.create({
-    name: req.body.name,
-    email: req.body.email,
-    password: req.body.password,  // hashed by Attribute mutator
-  })
-  await auth().login(user)
-  res.json({ user })
-})
-
-router.post('/auth/logout', RequireAuth(), async (req, res) => {
-  await auth().logout()
-  res.json({ message: 'Logged out.' })
-})
-```
-
-### 7. Set up auth views (login/register pages)
-
-Vendor the view files into your app:
-
-```bash
-pnpm rudder vendor:publish --tag=auth-views
-```
-
-This copies `@rudderjs/auth/views/react/` into `app/Views/Auth/`. Then register routes:
-
-```ts
-// routes/web.ts
-import { Route } from '@rudderjs/router'
-import { registerAuthRoutes } from '@rudderjs/auth/routes'
-
-registerAuthRoutes(Route)
-// Registers: GET /login, GET /register, GET /forgot-password, GET /reset-password
-```
-
-Customize paths and view ids:
-
-```ts
-registerAuthRoutes(Route, {
-  paths: {
-    login: '/sign-in',
-    register: '/sign-up',
-  },
-  views: {
-    login: 'auth.sign-in',       // maps to app/Views/Auth/SignIn.tsx
-    register: 'auth.sign-up',
-  },
-  homeUrl: '/dashboard',          // redirect destination for authenticated users
-})
-```
-
-### 8. Authorization with Gates
-
-```ts
-import { Gate, Policy, AuthorizationError } from '@rudderjs/auth'
-
-// Define abilities
-Gate.define('manage-settings', (user) => user.role === 'admin')
-Gate.define('edit-post', (user, post) => post.authorId === user.getAuthIdentifier())
-
-// Check in handlers
-if (await Gate.allows('manage-settings')) { /* ... */ }
-if (await Gate.denies('edit-post', post)) { /* ... */ }
-
-// Throw 403 if denied
-await Gate.authorize('edit-post', post)
-
-// Before callback -- runs before all checks
-Gate.before((user, ability) => {
-  if (user.role === 'super-admin') return true  // allow everything
-  return null  // fall through to normal checks
-})
-```
-
-### 9. Model policies
-
-```ts
-import { Policy } from '@rudderjs/auth'
-import type { Authenticatable } from '@rudderjs/auth'
-
-class PostPolicy extends Policy {
-  before(user: Authenticatable) {
-    if ((user as any).role === 'admin') return true
-    return null  // fall through
-  }
-
-  view(user: Authenticatable, post: Post) {
-    return post.isPublished || post.authorId === user.getAuthIdentifier()
-  }
-
-  update(user: Authenticatable, post: Post) {
-    return post.authorId === user.getAuthIdentifier()
-  }
-
-  delete(user: Authenticatable, post: Post) {
-    return post.authorId === user.getAuthIdentifier()
-  }
-}
-
-// Register the policy
-Gate.policy(Post, PostPolicy)
-
-// Use it
-await Gate.authorize('update', post)  // auto-finds PostPolicy.update()
-```
-
-### 10. Email verification
-
-```ts
-import { EnsureEmailIsVerified, verificationUrl, handleEmailVerification } from '@rudderjs/auth'
-import type { MustVerifyEmail } from '@rudderjs/auth'
-
-// Make user implement MustVerifyEmail
-class User extends Model implements Authenticatable, MustVerifyEmail {
-  hasVerifiedEmail() { return this.emailVerifiedAt !== null }
-  async markEmailAsVerified() { await User.update(this.id, { emailVerifiedAt: new Date() }) }
-  getEmailForVerification() { return this.email }
-}
-
-// Protect routes
-router.get('/dashboard', RequireAuth(), EnsureEmailIsVerified(), handler)
-
-// Generate verification URL (for sending in emails)
-const url = verificationUrl(user)
-```
-
-### 11. Password reset
-
-```ts
-import { PasswordBroker, MemoryTokenRepository } from '@rudderjs/auth'
-
-const broker = new PasswordBroker(new MemoryTokenRepository())
-// In production, implement TokenRepository backed by your database
-```
+- **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` for configuration, `playground/app/Models/User.ts` for the model, `playground/routes/web.ts` for route registration, and `playground/app/Views/Auth/` for vendored view files.
-
-## Common pitfalls
-
-- **Ghost signed-in user**: `AuthManager` must NOT cache `SessionGuard` instances. The manager is a DI singleton; cached guards leak `_user` across requests.
-- **Provider boot order**: `HashProvider` and `SessionProvider` must boot before `AuthProvider`. With `defaultProviders()`, this is handled automatically.
-- **Session middleware required**: Auth views require session middleware. Ensure `@rudderjs/session` is installed and its provider is registered.
-- **View route override**: Auth view files need `export const route = '/login'` etc. so SPA navigation works correctly (URL must match Vike's route table).
-- **POST handlers not included**: `registerAuthRoutes()` only registers GET routes for the UI pages. POST endpoints for login/register/logout are your responsibility in `routes/api.ts`.
-- **Guard driver**: Currently only `'session'` is supported as a guard driver. API token guards are planned.
+See `playground/config/auth.ts`, `playground/app/Models/User.ts`, `playground/routes/web.ts`, and `playground/app/Views/Auth/`.

package/boost/skills/auth-setup/rules/auth-views.md

@@ -0,0 +1,90 @@
+# Auth Views (Login / Register UI)
+
+## Vendor the view files
+
+`@rudderjs/auth` ships React and Vue auth views. Vendor them into your app:
+
+```bash
+pnpm rudder vendor:publish --tag=auth-views
+```
+
+This copies `@rudderjs/auth/views/react/` (or `/vue/`) into `app/Views/Auth/`. After vendoring, the files belong to your app — edit them freely.
+
+## Register the controller routes
+
+```ts
+// routes/web.ts
+import { Route } from '@rudderjs/router'
+import { registerAuthRoutes } from '@rudderjs/auth/routes'
+
+registerAuthRoutes(Route)
+```
+
+`registerAuthRoutes(Route)` registers:
+
+| URL | View id |
+|---|---|
+| `GET /login`           | `auth.login` |
+| `GET /register`        | `auth.register` |
+| `GET /forgot-password` | `auth.forgot-password` |
+| `GET /reset-password`  | `auth.reset-password` |
+
+The view-id mapping uses `view('id', props)` and lands in `app/Views/Auth/<File>.tsx`.
+
+## Customize paths and view ids
+
+```ts
+registerAuthRoutes(Route, {
+  paths: {
+    login:    '/sign-in',
+    register: '/sign-up',
+  },
+  views: {
+    login:    'auth.sign-in',     // maps to app/Views/Auth/SignIn.tsx
+    register: 'auth.sign-up',
+  },
+  homeUrl: '/dashboard',          // redirect destination for authenticated users
+})
+```
+
+## Add the `route` export to vendored views
+
+Vendored auth views need an explicit URL because the id-derived default (`/auth/login`) doesn't match the controller route (`/login`).
+
+```tsx
+// app/Views/Auth/Login.tsx
+export const route = '/login'
+
+export default function Login(props: { /* ... */ }) { /* ... */ }
+```
+
+Without this, **SPA navigation falls back to full page reloads** because Vike's client route table doesn't match the browser URL.
+
+## Pitfalls
+
+❌ **Don't** assume POST handlers come from `registerAuthRoutes`:
+
+```ts
+registerAuthRoutes(Route)
+// ❌ POST /login / POST /register / POST /logout — those are YOUR job
+```
+
+✅ **Do** add them in `routes/api.ts` or `routes/web.ts` using `auth().attempt()` / `auth().login()` / `auth().logout()`.
+
+❌ **Don't** skip the `route` export when customizing URLs:
+
+```tsx
+// app/Views/Auth/Login.tsx — no route export
+export default function Login() { /* ... */ }
+```
+
+✅ **Do** add it so SPA nav works:
+
+```tsx
+export const route = '/sign-in'
+export default function Login() { /* ... */ }
+```
+
+❌ **Don't** mix `vike-react` and `vike-vue` — the scanner errors at boot.
+
+✅ **Do** pick one renderer per project; vendor the matching auth views (`--tag=auth-views` auto-detects).

package/boost/skills/auth-setup/rules/email-and-password-reset.md

@@ -0,0 +1,91 @@
+# Email Verification + Password Reset
+
+## Email verification
+
+Implement `MustVerifyEmail` on your User model:
+
+```ts
+import type { Authenticatable, MustVerifyEmail } from '@rudderjs/auth'
+
+class User extends Model implements Authenticatable, MustVerifyEmail {
+  hasVerifiedEmail()         { return this.emailVerifiedAt !== null }
+  getEmailForVerification()  { return this.email }
+  async markEmailAsVerified() {
+    await User.update(this.id, { emailVerifiedAt: new Date() })
+  }
+}
+```
+
+Protect routes that require a verified email:
+
+```ts
+import { RequireAuth, EnsureEmailIsVerified } from '@rudderjs/auth'
+
+router.get('/dashboard', RequireAuth(), EnsureEmailIsVerified(), handler)
+```
+
+Generate a signed URL to send in an email:
+
+```ts
+import { verificationUrl } from '@rudderjs/auth'
+
+const url = verificationUrl(user)
+// Sign-protected — calling it with a tampered signature returns 403
+```
+
+Handle the click:
+
+```ts
+import { handleEmailVerification } from '@rudderjs/auth'
+
+router.get('/verify-email/:id/:hash', async (req, res) => {
+  await handleEmailVerification(req.params.id, req.params.hash, (id) => User.find(id))
+  res.redirect('/dashboard')
+})
+```
+
+## Password reset
+
+The `PasswordBroker` orchestrates token generation, email dispatch, and verification. A token repository persists the tokens.
+
+```ts
+import { PasswordBroker, MemoryTokenRepository } from '@rudderjs/auth'
+
+const broker = new PasswordBroker(new MemoryTokenRepository())
+```
+
+In production, implement `TokenRepository` backed by your database:
+
+```ts
+import type { TokenRepository } from '@rudderjs/auth'
+
+class PrismaTokenRepository implements TokenRepository {
+  async create(email: string, token: string) { /* INSERT */ }
+  async findByEmailAndToken(email: string, token: string) { /* SELECT */ }
+  async delete(email: string) { /* DELETE */ }
+  async deleteExpired(thresholdMs: number) { /* DELETE WHERE created_at < ... */ }
+}
+```
+
+## Pitfalls
+
+❌ **Don't** ship `MemoryTokenRepository` to production — tokens evaporate on restart, and multi-process / multi-worker setups never share state.
+
+✅ **Do** persist tokens via your ORM (Prisma/Drizzle) and run a scheduled cleanup of expired rows.
+
+❌ **Don't** assume `verificationUrl(user)` works without `APP_KEY`:
+
+```ts
+// Throws if APP_KEY isn't set
+const url = verificationUrl(user)
+```
+
+✅ **Do** set `APP_KEY` in `.env` (or call `Url.setKey('test-key')` in tests).
+
+❌ **Don't** roll a hand-crafted signature on the verification URL:
+
+```ts
+const url = `/verify-email/${user.id}/${crypto.createHash(...)}`
+```
+
+✅ **Do** use `verificationUrl(user)` — it uses HMAC-SHA256 with timing-safe comparison via `@rudderjs/router`'s `Url`.

package/boost/skills/auth-setup/rules/gates-and-policies.md

@@ -0,0 +1,110 @@
+# Gates and Policies
+
+`Gate` is the imperative authorization API; `Policy` classes group abilities per model.
+
+## Define abilities
+
+```ts
+import { Gate } from '@rudderjs/auth'
+
+Gate.define('manage-settings', (user) => user.role === 'admin')
+Gate.define('edit-post',       (user, post) => post.authorId === user.getAuthIdentifier())
+```
+
+## Check in route handlers
+
+```ts
+// Returns boolean
+if (await Gate.allows('manage-settings')) { /* ... */ }
+if (await Gate.denies('edit-post', post)) { /* ... */ }
+
+// Throws 403 on denial
+await Gate.authorize('edit-post', post)
+```
+
+`authorize` throws `AuthorizationError` which the framework maps to a `403` response.
+
+## Before callback
+
+Runs before every gate check — useful for super-admins:
+
+```ts
+Gate.before((user, ability) => {
+  if (user.role === 'super-admin') return true   // allow everything
+  return null                                     // fall through to normal checks
+})
+```
+
+Return `true` to allow, `false` to deny, `null` to fall through.
+
+## Model policies
+
+```ts
+import { Policy } from '@rudderjs/auth'
+import type { Authenticatable } from '@rudderjs/auth'
+
+class PostPolicy extends Policy {
+  before(user: Authenticatable) {
+    if ((user as { role?: string }).role === 'admin') return true
+    return null
+  }
+
+  view(user: Authenticatable, post: Post) {
+    return post.isPublished || post.authorId === user.getAuthIdentifier()
+  }
+
+  update(user: Authenticatable, post: Post) {
+    return post.authorId === user.getAuthIdentifier()
+  }
+
+  delete(user: Authenticatable, post: Post) {
+    return post.authorId === user.getAuthIdentifier()
+  }
+}
+
+Gate.policy(Post, PostPolicy)
+```
+
+Method names on the policy class match ability names. `Gate.authorize('update', post)` looks up `PostPolicy.update(user, post)`.
+
+## Pitfalls
+
+❌ **Don't** call `Gate.authorize` outside an auth context expecting it to throw 401:
+
+```ts
+// In a job — no auth context, user is null, gate throws AuthorizationError as 403
+await Gate.authorize('edit-post', post)
+```
+
+✅ **Do** check authentication first or scope the gate explicitly:
+
+```ts
+await Gate.forUser(user).authorize('edit-post', post)
+```
+
+❌ **Don't** rely on policy autoloading from disk:
+
+```ts
+// Putting app/Policies/PostPolicy.ts on disk does NOT auto-register it
+```
+
+✅ **Do** register policies in a service provider's `boot()`:
+
+```ts
+// app/Providers/AppServiceProvider.ts
+boot() {
+  Gate.policy(Post, PostPolicy)
+}
+```
+
+❌ **Don't** return non-boolean from a `define` callback expecting it to count:
+
+```ts
+Gate.define('edit-post', (user, post) => post.authorId)   // truthy number, but not boolean
+```
+
+✅ **Do** return a boolean explicitly:
+
+```ts
+Gate.define('edit-post', (user, post) => post.authorId === user.getAuthIdentifier())
+```