К основному содержанию
скилл CX Codex

auth-and-guards — скилл для TanStack Router: защита маршрутов

Скилл auth-and-guards для защиты маршрутов в TanStack Router. Перенаправляет неавторизованных пользователей, встраивает проверку ролей и прав, интегрирует Auth0, Clerk, Supabase через контекст роутера.

MIT 219 установок ★ 15 341 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add TanStack/router --skill auth-and-guards -a claude-code
Открыть на GitHub

Что делает auth-and-guards

auth-and-guards учит ИИ-кодеру строить авторизацию на стороне маршрутизации. Основной инструмент — функция beforeLoad в патчлесс-раутах вроде _authenticated, которая перенаправляет на логин или показывает форму на месте. Скилл покрывает четыре паттерна: перенаправление с сохранением адреса назад, встроенный логин без смены URL, RBAC с ролями и правами, интеграция внешних провайдеров через createRootRouteWithContext.

Авт состояние передаётся в роутер через пропс context компонента RouterProvider — это позволяет обновлять авторизацию без пересоздания роутера. Скилл напоминает, что гварды защищают только навигацию и UX: если на маршруте объявлена createServerFn, она остаётся открытым API-эндпойнтом и требует собственных проверок на сервере. Для запуска нужны React и TanStack Router версии 1.171.15+.

Какие задачи решает

  • Перенаправить неавторизованного пользователя на форму логина с сохранением целевого маршрута
  • Показать логин-форму на месте вместо защищённого контента
  • Проверить роль или право пользователя перед входом в маршрут
  • Подключить Auth0, Clerk или Supabase как источник авт состояния

Примеры запросов агенту

  • Создай защищённый маршрут, который перенаправляет на /login, если пользователь не залогинен
  • Запросте авт состояние из контекста роутера и покажи имя пользователя
  • Проверь роль admin перед входом в /admin/dashboard

Как установить auth-and-guards

1Через Skills CLI (Vercel)

npx skills add TanStack/router --skill auth-and-guards -a claude-code

2Вручную: положить файлы

~/.claude/skills/auth-and-guards/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/auth-and-guards/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об auth-and-guards

Как установить auth-and-guards в Claude Code?

Выполни npx skills add TanStack/router --skill auth-and-guards -a claude-code, затем открой ~/.claude/skills/auth-and-guards/SKILL.md.

Что делает auth-and-guards?

Учит ИИ-кодеру защищать маршруты через beforeLoad, перенаправлять неавторизованных на логин, встраивать RBAC и интегрировать авт-провайдеров в контекст TanStack Router.

Защищают ли гварды маршрута функции createServerFn?

Нет. Гварды контролируют только навигацию. Серверные функции — это самостоятельные API-эндпойнты и требуют отдельных проверок авторизации на сервере.

Исходный текст

SKILL.md · MIT
---
name: auth-and-guards
description: >-
  Route protection with beforeLoad, redirect()/throw redirect(),
  isRedirect helper, authenticated layout routes (_authenticated),
  non-redirect auth (inline login), RBAC with roles and permissions,
  auth provider integration (Auth0, Clerk, Supabase), router context
  for auth state.
metadata:
  type: sub-skill
  library: tanstack-router
  library_version: '1.171.15'
requires:
  - router-core
sources:
  - TanStack/router:docs/router/guide/authenticated-routes.md
  - TanStack/router:docs/router/how-to/setup-authentication.md
  - TanStack/router:docs/router/how-to/setup-auth-providers.md
  - TanStack/router:docs/router/how-to/setup-rbac.md
---

# Auth and Guards

> **This skill covers the routing side of auth.** Route guards are UX and navigation control; the data/API boundary still belongs in the server function, server route, or API endpoint that reads or mutates private data. For the **server-side primitives** — session cookies (`HttpOnly`/`Secure`/`SameSite`), external session helpers, OAuth `state` + PKCE, password-reset enumeration defense, CSRF, rate limiting — see `@tanstack/start-client-core#start-core/auth-server-primitives`.
>
> **CRITICAL**: A route guard (`beforeLoad`) does NOT protect a `createServerFn` declared on that route. Server functions are API endpoints reachable independently of the route that calls them. See "Route guards do not protect server functions" below.

## Setup

Protect routes with `beforeLoad` + `redirect()` in a pathless layout route (`_authenticated`):

```tsx
// src/routes/_authenticated.tsx
import { createFileRoute, redirect } from '@tanstack/react-router'

export const Route = createFileRoute('/_authenticated')({
  beforeLoad: ({ context, location }) => {
    if (!context.auth.isAuthenticated) {
      throw redirect({
        to: '/login',
        search: {
          redirect: location.href,
        },
      })
    }
  },
  // component defaults to Outlet — no need to declare it
})
```

Any route file placed under `src/routes/_authenticated/` is automatically protected:

```tsx
// src/routes/_authenticated/dashboard.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/_authenticated/dashboard')({
  component: DashboardComponent,
})

function DashboardComponent() {
  const { auth } = Route.useRouteContext()
  return <div>Welcome, {auth.user?.username}</div>
}
```

## Core Patterns

### Router Context for Auth State

Auth state flows into the router via `createRootRouteWithContext` and `RouterProvider`'s `context` prop:

```tsx
// src/routes/__root.tsx
import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'

interface AuthState {
  isAuthenticated: boolean
  user: { id: string; username: string; email: string } | null
  login: (username: string, password: string) => Promise<void>
  logout: () => void
}

interface MyRouterContext {
  auth: AuthState
}

export const Route = createRootRouteWithContext<MyRouterContext>()({
  component: () => <Outlet />,
})
```

```tsx
// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

export const router = createRouter({
  routeTree,
  context: {
    auth: undefined!, // placeholder — filled by RouterProvider context prop
  },
})

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}
```

```tsx
// src/App.tsx
import { RouterProvider } from '@tanstack/react-router'
import { AuthProvider, useAuth } from './auth'
import { router } from './router'

function InnerApp() {
  const auth = useAuth()
  // context prop injects live auth state WITHOUT recreating the router
  return <RouterProvider router={router} context={{ auth }} />
}

function App() {
  return (
    <AuthProvider>
      <InnerApp />
    </AuthProvider>
  )
}
```

The router is created once with a placeholder. `RouterProvider`'s `context` prop injects the live auth state on each render — this avoids recreating the router on auth changes (which would reset caches and rebuild the route tree).

### Redirect-Based Auth with Redirect-Back

Save the current location in search params so you can redirect back after login:

```tsx
// src/routes/_authenticated.tsx
import { createFileRoute, redirect } from '@tanstack/react-router'

export const Route = createFileRoute('/_authenticated')({
  beforeLoad: ({ context, location }) => {
    if (!context.auth.isAuthenticated) {
      throw redirect({
        to: '/login',
        search: { redirect: location.href },
      })
    }
  },
})
```

```tsx
// src/routes/login.tsx
import { createFileRoute, redirect } from '@tanstack/react-router'
import { useState, type FormEvent } from 'react'

// Validate redirect target to prevent open redirect attacks
function sanitizeRedirect(url: unknown): string {
  if (typeof url !== 'string' || !url.startsWith('/') || url.startsWith('//')) {
    return '/'
  }
  return url
}

export const Route = createFileRoute('/login')({
  validateSearch: (search) => ({
    redirect: sanitizeRedirect(search.redirect),
  }),
  beforeLoad: ({ context, search }) => {
    if (context.auth.isAuthenticated) {
      throw redirect({ to: search.redirect })
    }
  },
  component: LoginComponent,
})

function LoginComponent() {
  const { auth } = Route.useRouteContext()
  const search = Route.useSearch()
  const navigate = Route.useNavigate()
  const [username, setUsername] = useState('')
  const [password, setPassword] = useState('')
  const [error, setError] = useState('')

  const handleSubmit = async (e: FormEvent) => {
    e.preventDefault()
    try {
      await auth.login(username, password)
      navigate({ to: search.redirect })
    } catch {
      setError('Invalid credentials')
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      {error && <div>{error}</div>}
      <input value={username} onChange={(e) => setUsername(e.target.value)} />
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
      />
      <button type="submit">Sign In</button>
    </form>
  )
}
```

### Non-Redirect Auth (Inline Login)

Instead of redirecting, show a login form in place of the `Outlet`:

```tsx
// src/routes/_authenticated.tsx
import { createFileRoute, Outlet } from '@tanstack/react-router'

export const Route = createFileRoute('/_authenticated')({
  component: AuthenticatedLayout,
})

function AuthenticatedLayout() {
  const { auth } = Route.useRouteContext()

  if (!auth.isAuthenticated) {
    return <LoginForm />
  }

  return <Outlet />
}
```

This keeps the URL unchanged — the user stays on the same page and sees a login form instead of protected content. After authentication, `<Outlet />` renders and child routes appear.

### RBAC with Roles and Permissions

Extend auth state with role/permission helpers, then check in `beforeLoad`:

```tsx
// src/auth.tsx
interface User {
  id: string
  username: string
  email: string
  roles: string[]
  permissions: string[]
}

interface AuthState {
  isAuthenticated: boolean
  user: User | null
  hasRole: (role: string) => boolean
  hasAnyRole: (roles: string[]) => boolean
  hasPermission: (permission: string) => boolean
  hasAnyPermission: (permissions: string[]) => boolean
  login: (username: string, password: string) => Promise<void>
  logout: () => void
}
```

Admin-only layout route:

```tsx
// src/routes/_authenticated/_admin.tsx
import { createFileRoute, redirect } from '@tanstack/react-router'

export const Route = createFileRoute('/_authenticated/_admin')({
  beforeLoad: ({ context, location }) => {
    if (!context.auth.hasRole('admin')) {
      throw redirect({
        to: '/unauthorized',
        search: { redirect: location.href },
      })
    }
  },
})
```

Multi-role access:

```tsx
// src/routes/_authenticated/_moderator.tsx
import { createFileRoute, redirect } from '@tanstack/react-router'

export const Route = createFileRoute('/_authenticated/_moderator')({
  beforeLoad: ({ context, location }) => {
    if (!context.auth.hasAnyRole(['admin', 'moderator'])) {
      throw redirect({
        to: '/unauthorized',
        search: { redirect: location.href },
      })
    }
  },
})
```

Permission-based:

```tsx
// src/routes/_authenticated/_users.tsx
import { createFileRoute, redirect } from '@tanstack/react-router'

export const Route = createFileRoute('/_authenticated/_users')({
  beforeLoad: ({ context, location }) => {
    if (!context.auth.hasAnyPermission(['users:read', 'users:write'])) {
      throw redirect({
        to: '/unauthorized',
        search: { redirect: location.href },
      })
    }
  },
})
```

Page-level permission check (nested under an already-role-protected layout):

```tsx
// src/routes/_authenticated/_users/manage.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/_authenticated/_users/manage')({
  beforeLoad: ({ context }) => {
    if (!context.auth.hasPermission('users:write')) {
      throw new Error('Write permission required')
    }
  },
  component: UserManagement,
})

function UserManagement() {
  const { auth } = Route.useRouteContext()
  const canDelete = auth.hasPermission('users:delete')

  return (
    <div>
      <h1>User Management</h1>
      {canDelete && <button>Delete User</button>}
    </div>
  )
}
```

### Handling Auth Check Failures (isRedirect)

When `beforeLoad` has a try/catch, redirects (which work by throwing) can get swallowed. Use `isRedirect` to re-throw:

```tsx
import { createFileRoute, redirect, isRedirect } from '@tanstack/react-router'

export const Route = createFileRoute('/_authenticated')({
  beforeLoad: async ({ context, location }) => {
    try {
      const user = await verifySession(context.auth)
      if (!user) {
        throw redirect({
          to: '/login',
          search: { redirect: location.href },
        })
      }
      return { user }
    } catch (error) {
      if (isRedirect(error)) throw error // re-throw redirect, don't swallow it
      // Actual error — redirect to login
      throw redirect({
        to: '/login',
        search: { redirect: location.href },
      })
    }
  },
})
```

## Common Mistakes

### CRITICAL: Route guards do not protect server functions

A `beforeLoad` redirect protects the **route's UI**, not the **server functions** declared on it. `createServerFn` produces an RPC endpoint reachable directly with its declared HTTP method regardless of which route renders the calling UI. An attacker doesn't have to load `/_authenticated/orders` — they can call this GET RPC endpoint directly.

```tsx
// WRONG — handler has no auth check; the route guard doesn't help
import { createServerFn } from '@tanstack/react-start'
import { createFileRoute, redirect } from '@tanstack/react-router'

const getMyOrders = createServerFn({ method: 'GET' }).handler(async () => {
  return db.orders.findMany() // ← anyone can hit the RPC
})

export const Route = createFileRoute('/_authenticated/orders')({
  beforeLoad: ({ context }) => {
    if (!context.auth.isAuthenticated) throw redirect({ to: '/login' })
  },
  loader: () => getMyOrders(),
})
```

```tsx
// CORRECT — auth enforced on the handler itself, via middleware
import { createServerFn } from '@tanstack/react-start'
import { authMiddleware } from '~/server/auth-middleware'

const getMyOrders = createServerFn({ method: 'GET' })
  .middleware([authMiddleware])
  .handler(async ({ context }) => {
    return db.orders.findMany({ where: { userId: context.session.userId } })
  })
```

Rule of thumb: every `createServerFn`, server route, or API endpoint that touches user data needs `authMiddleware` (or an equivalent in-handler check). The route guard is for the page experience; the endpoint guard is for the data. See `@tanstack/start-client-core#start-core/auth-server-primitives` for the full session/middleware pattern.

### CRITICAL: The anonymous destination can still disclose protected data

Protect the entire anonymous response, not only the API call. A public login or unauthorized page still leaks data if its title, copy, search params, or serialized loader state names the protected user, tenant, record, or resource. Test a direct anonymous request and follow redirects. Assert that the handler rejects before reading private data, no protected loader runs, the final HTML and serialized state contain no protected identity, and the redirect contains only a sanitized relative return URL.

### HIGH: Auth check in component instead of beforeLoad

Component-level auth checks cause a **flash of protected content** before the redirect:

```tsx
// WRONG — protected content renders briefly before redirect
export const Route = createFileRoute('/_authenticated/dashboard')({
  component: () => {
    const auth = useAuth()
    if (!auth.isAuthenticated) return <Navigate to="/login" />
    return <Dashboard />
  },
})

// CORRECT — beforeLoad runs before any rendering
export const Route = createFileRoute('/_authenticated/dashboard')({
  beforeLoad: ({ context }) => {
    if (!context.auth.isAuthenticated) {
      throw redirect({ to: '/login' })
    }
  },
  component: Dashboard,
})
```

### HIGH: Not re-throwing redirects in try/catch

`redirect()` works by throwing. If `beforeLoad` has a try/catch, the redirect gets swallowed:

```tsx
// WRONG — redirect is caught and swallowed
beforeLoad: async ({ context }) => {
  try {
    await validateSession(context.auth)
  } catch (e) {
    console.error(e) // swallows the redirect!
  }
}

// CORRECT — use isRedirect to distinguish intentional redirects from errors
import { isRedirect } from '@tanstack/react-router'

beforeLoad: async ({ context }) => {
  try {
    await validateSession(context.auth)
  } catch (e) {
    if (isRedirect(e)) throw e
    console.error(e)
  }
}
```

### MEDIUM: Conditionally rendering root route component

The root route always renders regardless of auth state. You cannot conditionally render its component:

```tsx
// WRONG — root route always renders, this doesn't protect anything
export const Route = createRootRoute({
  component: () => {
    if (!isAuthenticated()) return <Login />
    return <Outlet />
  },
})

// CORRECT — use a pathless layout route for auth boundaries
// src/routes/_authenticated.tsx
export const Route = createFileRoute('/_authenticated')({
  beforeLoad: ({ context }) => {
    if (!context.auth.isAuthenticated) {
      throw redirect({ to: '/login' })
    }
  },
})
```

Place protected routes as children of the `_authenticated` layout route. Public routes (login, home, etc.) live outside it.

## Cross-References

- See also: **router-core/data-loading/SKILL.md** — `beforeLoad` runs before `loader`; auth context flows into loader via route context
- See also: **start-core/auth-server-primitives/SKILL.md** — server-side session cookies, OAuth state + PKCE, CSRF, password-reset hardening, rate limiting (the server half of authentication)
- See also: **start-core/middleware/SKILL.md** — `authMiddleware` factory pattern for protecting individual `createServerFn` calls

© TanStack · MIT · TanStack/router

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →
auth-wasp-drone Legion Code Inc. Субагент auth-wasp-drone помогает спроектировать и внедрить аутентификацию: выбрать провайдера, настроить OAuth, MFA, RBAC и сессии. CX Codex ★ 96звёзд репо workos-wasp-drone Legion Code Inc. Субагент workos-wasp-drone для интеграции WorkOS: AuthKit (UI и headless), сессии, User Management, RBAC, SSO (SAML/OIDC), Directory Sync, MFA и миграция с Supabase Auth или Clerk. CX Codex ★ 96звёзд репо better-auth mrgoonie Проводит по подключению Better Auth: email-пароли, OAuth, 2FA, passkeys и роли. Встраивает вход и сессии в TypeScript-проект. CX Codex +1 402установок server-auth-actions zebbern Правило server-auth-actions требует проверять аутентификацию и права внутри каждой Server Action. Оно защищает серверные мутации, которые можно вызвать напрямую. CX Codex +1 ★ 4 719звёзд репо nextjs-supabase-auth sickn33 Скилл nextjs-supabase-auth для Claude Code настраивает Supabase Auth в Next.js App Router: клиенты, middleware, OAuth callback и Server Actions. Защищает маршруты и работает с сессиями. CX Codex +1 6 600установок rbac-permissions-builder patricio0312rev Скилл rbac-permissions-builder проектирует ролевую модель доступа на TypeScript: от матрицы прав и Express middleware до классов политик и проверок в интерфейсе. Пригодится при настройке авторизации в API. CX Codex +1 337установок

Из того же набора25

Весь набор →
data-loading Скилл data-loading помогает настраивать загрузку данных в TanStack Router: кэш, состояния ожидания, ошибки и контекст роутера. CX Codex +1 230установок search-params Скилл search-params добавляет ассистенту правила работы со строкой поиска в TanStack Router: валидацию через Zod, наследование в дочерних маршрутах и middleware. CX Codex +1 228установок type-safety Скилл type-safety учит ИИ-кодеру правильно писать типизированный код с TanStack Router: не добавлять аннотации к выведенным значениям, использовать Register, сужать типы через from и getRouteApi. CX Codex +1 223установок server-functions Скилл server-functions обучает агента писать типобезопасные RPC-функции через createServerFn в TanStack Start, валидировать входные данные схемами Zod и вызывать их из компонентов. CX Codex +1 221установок navigation Скилл navigation помогает агенту настраивать навигацию в TanStack Router: ссылки, переходы, предзагрузку маршрутов и блокировку ухода со страницы. CX Codex +1 214установок execution-model Скилл execution-model помогает агенту правильно разделять серверный и клиентский код в TanStack Start и учитывать SSR, гидрацию и переменные окружения. CX Codex +1 214установок code-splitting Скилл code-splitting разделяет код маршрутов TanStack Router на критичную и ленивую части: автоматически создаёт отдельные чанки или позволяет настроить разделение вручную. CX Codex +1 212установок not-found-and-errors Скилл not-found-and-errors обучает агента настраивать экраны 404 и обработку ошибок в TanStack Router. Помогает пробросить notFound() из loader и оформить запасной UI. CX Codex +1 211установок

Ещё в каталоге

PriorSeal imokokok MCP-сервер PriorSeal связывает подписанное пользователем разрешение с конкретной транзакцией в EVM или Solana и выдаёт переносимую квитанцию, которую проверяет третья сторона. CX Codex +1 ★ 6звёзд репо add-authentication-system davila7 Команда add-authentication-system добавляет в приложение систему аутентификации с выбранным методом входа. Она охватывает управление пользователями, сессии, права доступа и защиту от типичных атак. CX Codex +1 382установок tanstack-router oakoss Скилл tanstack-router настраивает типобезопасную файловую маршрутизацию в React через @tanstack/react-router. Помогает с лоадерами данных, валидацией параметров поиска и разделением кода. CX Codex +1 150установок backend-api-security Seth Hobson Плагин backend-api-security для Claude Code помогает укреплять защиту API. Он охватывает аутентификацию, авторизацию, ограничение частоты запросов и проверку входных данных. CX Codex ★ 42 780звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой