Skip to content

Commit 8cf5541

Browse files
committed
docs: clarify auth data boundaries
1 parent bae50be commit 8cf5541

13 files changed

Lines changed: 65 additions & 30 deletions

File tree

‎docs/router/guide/authenticated-routes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ title: Authenticated Routes
55

66
Authentication is an extremely common requirement for web applications. In this guide, we'll walk through how to use TanStack Router to build protected routes, and how to redirect users to login if they try to access them.
77

8-
> **A route guard does not protect a server function.** This guide shows how to gate a route's UI behind `beforeLoad`. If you also have a `createServerFn` that fetches sensitive data, the route guard does NOT stop a direct request to that RPC — server functions are reachable by POST regardless of which route renders them. Pair routing-side guards with **handler-level enforcement** (auth middleware or in-handler check). See [Authentication Server Primitives](../../start/framework/react/guide/authentication-server-primitives.md) in the Start docs.
8+
> **A route guard is not a data authorization boundary.** This guide shows how to gate a route's UI behind `beforeLoad`. Any server function, server route, or API endpoint that returns private data must authorize the request itself, because it can be requested independently of the route that calls it. See [Authentication Server Primitives](../../start/framework/react/guide/authentication-server-primitives.md) in the Start docs.
99
1010
## The `route.beforeLoad` Option
1111

‎docs/start/config.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,10 @@
165165
"label": "Authentication Overview",
166166
"to": "framework/react/guide/authentication-overview"
167167
},
168+
{
169+
"label": "Authentication Server Primitives",
170+
"to": "framework/react/guide/authentication-server-primitives"
171+
},
168172
{
169173
"label": "Authentication",
170174
"to": "framework/react/guide/authentication"
@@ -290,6 +294,10 @@
290294
"label": "Authentication Overview",
291295
"to": "framework/solid/guide/authentication-overview"
292296
},
297+
{
298+
"label": "Authentication Server Primitives",
299+
"to": "framework/solid/guide/authentication-server-primitives"
300+
},
293301
{
294302
"label": "Authentication",
295303
"to": "framework/solid/guide/authentication"

‎docs/start/framework/react/guide/authentication-overview.md‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -72,11 +72,11 @@ title: Authentication
7272
- Good for mixed public/private content on same route
7373
- Requires careful handling to prevent layout shifts
7474

75-
**Server Function Guards**
75+
**Data/API Protection (Security Boundary)**
7676

77-
- Server-side validation before executing sensitive operations
78-
- Works alongside route-level protection
79-
- Essential for API security regardless of client-side protection
77+
- Authorize every server function, server route, or API endpoint that reads or writes private data
78+
- Reject unauthorized requests even if no protected route was loaded first
79+
- Treat route guards as UX and navigation control, not as the data boundary
8080

8181
### State Management Patterns
8282

@@ -207,14 +207,17 @@ Build your own authentication system using TanStack Start's server functions and
207207
- Specific business logic needs
208208
- Full ownership of authentication data
209209

210-
### Security Considerations
211-
212-
- Use HTTPS in production
213-
- Use HTTP-only cookies when possible
214-
- Validate all inputs on the server
215-
- Keep secrets in server-only functions
216-
- Implement rate limiting for auth endpoints
217-
- Use CSRF protection for form submissions
210+
### Production Auth Checklist
211+
212+
- Use HTTPS in production and set a strong session secret.
213+
- Store sessions in `HttpOnly`, `Secure`, `SameSite` cookies. Do not store session tokens in `localStorage` or `sessionStorage`.
214+
- Enforce auth in every server function, server route, or API endpoint that reads or writes private user, tenant, or account data. Use `beforeLoad` for page UX, not as the data boundary.
215+
- Use `.inputValidator()` on every server function that accepts input.
216+
- Hash passwords with bcrypt, scrypt, or Argon2. For missing users, verify against a dummy hash and return the same login/reset message.
217+
- Rate limit login, registration, and password-reset endpoints.
218+
- Use CSRF or same-origin protections for non-GET server functions and server routes.
219+
- Log authentication events and monitor failures.
220+
- Test direct unauthenticated calls to protected server functions; they should reject before returning data.
218221

219222
## Next Steps
220223

‎docs/start/framework/react/guide/authentication-server-primitives.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,14 @@ This guide covers the **server-side primitives** for building authentication in
77

88
If you can use a managed solution like [Clerk](https://go.clerk.com/wOwHtuJ) or [WorkOS](https://workos.com/), prefer that — they handle most of what this guide describes. Read on if you're rolling your own.
99

10-
## The Two Halves of Auth
10+
## Protect Data First
1111

12-
Authentication has a routing half and a server half. They both need to be implemented; either one alone is incomplete.
12+
Authentication has a data/API boundary and a route/UI layer. The data boundary is the security boundary: every server function, server route, or API endpoint that reads or writes private data must authorize the request before returning data or mutating state.
1313

14-
- **Routing half** (`router-core/auth-and-guards`): redirect unauthenticated users away from protected pages, gate UI on roles/permissions, surface a login form.
15-
- **Server half** (this guide): issue and verify session cookies, exchange OAuth codes, hash and verify passwords, rate-limit credential endpoints, defeat user enumeration.
14+
- **Data/API boundary** (this guide): issue and verify session cookies, exchange OAuth codes, hash and verify passwords, rate-limit credential endpoints, defeat user enumeration, and authorize private data access.
15+
- **Route/UI layer** (`router-core/auth-and-guards`): redirect unauthenticated users away from screens they cannot use, gate UI on roles/permissions, surface a login form, and avoid triggering requests that would fail anyway.
1616

17-
> **A route guard does NOT protect a `createServerFn` on that route.** Server functions are RPC endpoints — they're reachable via direct POST regardless of which route renders them. Auth must be enforced on the handler (or via middleware), not on the calling route.
17+
> **A route guard is not a data authorization boundary.** Server functions and server routes are API endpoints; they are reachable independently of the route that calls them. Auth must be enforced in the handler or middleware for the endpoint that touches private data. `beforeLoad` is for route UX.
1818
1919
## Session Cookies
2020

‎docs/start/framework/react/guide/authentication.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ Authentication involves many considerations including password security, session
3636

3737
TanStack Start provides the tools for both through server functions, sessions, and route protection.
3838

39+
> Protect the data/API boundary first. Any server function, server route, or other API endpoint that returns or mutates private data must authorize the request itself. `beforeLoad` is useful for route UX: it keeps users out of screens they cannot use and avoids triggering work that would fail anyway. It is not the security boundary for the data. See [Authentication Server Primitives](./authentication-server-primitives.md) for the server-side pattern.
40+
3941
## Essential Building Blocks
4042

4143
### 1. Server Functions for Authentication

‎docs/start/framework/react/guide/middleware.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -822,7 +822,7 @@ Static middlewares are created once and reused across routes. A middleware facto
822822

823823
This middleware validates the session and injects it into `context` for downstream middlewares.
824824

825-
> **Attach `authMiddleware` to every `createServerFn` that needs auth.** A route `beforeLoad` redirect protects the page experience but does NOT protect the RPC — server functions are reachable via direct POST regardless of which route renders them. Pair routing-side guards with handler-level enforcement here. See [Authentication Server Primitives](./authentication-server-primitives.md).
825+
> **Attach `authMiddleware` to every `createServerFn` that needs auth.** Server functions are API endpoints, so protect the endpoint that reads or mutates private data. A route `beforeLoad` guard improves route UX, but it is not the data boundary. See [Authentication Server Primitives](./authentication-server-primitives.md).
826826
827827
```tsx
828828
// middleware.ts

‎docs/start/framework/react/guide/server-functions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -397,7 +397,7 @@ Use server functions without JavaScript by leveraging the `.url` property with H
397397

398398
Compose server functions with middleware for authentication, logging, and shared logic. See the [Middleware guide](./middleware.md).
399399

400-
> **Auth must be enforced on the server function, not the route.** A `createServerFn` is an RPC endpoint reachable by direct POST regardless of which route renders the calling UI — a route `beforeLoad` redirect protects the page experience, but it does not stop a request from hitting the RPC directly. Apply `authMiddleware` (or an equivalent in-handler check) to every server function that needs auth. See [Authentication Server Primitives](./authentication-server-primitives.md).
400+
> **Protect data in the endpoint that serves it.** Server functions are API endpoints reachable independently of whichever route renders the calling UI. Apply `authMiddleware` or an equivalent in-handler check to every server function that reads or writes private data. `beforeLoad` is useful route UX, but it is not the data boundary. See [Authentication Server Primitives](./authentication-server-primitives.md).
401401
402402
### Static Server Functions
403403

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
ref: docs/start/framework/react/guide/authentication-server-primitives.md
3+
replace:
4+
{
5+
'@tanstack/react-start': '@tanstack/solid-start',
6+
'@tanstack/react-router': '@tanstack/solid-router',
7+
'React': 'SolidJS',
8+
}
9+
---

‎docs/start/framework/solid/guide/authentication.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ Authentication involves many considerations including password security, session
3636

3737
TanStack Start provides the tools for both through server functions, sessions, and route protection.
3838

39+
> Protect the data/API boundary first. Any server function, server route, or other API endpoint that returns or mutates private data must authorize the request itself. `beforeLoad` is useful for route UX: it keeps users out of screens they cannot use and avoids triggering work that would fail anyway. It is not the security boundary for the data. See [Authentication Server Primitives](./authentication-server-primitives.md) for the server-side pattern.
40+
3941
## Essential Building Blocks
4042

4143
### 1. Server Functions for Authentication

‎packages/router-core/skills/router-core/auth-and-guards/SKILL.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,9 @@ sources:
2121

2222
# Auth and Guards
2323

24-
> **This skill covers the routing side of auth.** For the **server-side primitives** — session cookies (`HttpOnly`/`Secure`/`SameSite`), `useSession`-style helpers, OAuth `state` + PKCE, password-reset enumeration defense, CSRF, rate limiting — see [start-core/auth-server-primitives](../../../../start-client-core/skills/start-core/auth-server-primitives/SKILL.md). The two skills are designed to be used together.
24+
> **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`), `useSession`-style helpers, OAuth `state` + PKCE, password-reset enumeration defense, CSRF, rate limiting — see [start-core/auth-server-primitives](../../../../start-client-core/skills/start-core/auth-server-primitives/SKILL.md).
2525
>
26-
> **CRITICAL**: A route guard (`beforeLoad`) does NOT protect a `createServerFn` declared on that route. Server functions are RPC endpoints reachable by direct POST regardless of which route renders them. See "Route guards do not protect server functions" below.
26+
> **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.
2727
2828
## Setup
2929

@@ -408,7 +408,7 @@ const getMyOrders = createServerFn({ method: 'GET' })
408408
})
409409
```
410410

411-
Rule of thumb: every `createServerFn` that touches user data needs `authMiddleware` (or an equivalent in-handler check). The route guard is for the page experience; the RPC guard is for the data. See [start-core/auth-server-primitives](../../../../start-client-core/skills/start-core/auth-server-primitives/SKILL.md) for the full session/middleware pattern.
411+
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 [start-core/auth-server-primitives](../../../../start-client-core/skills/start-core/auth-server-primitives/SKILL.md) for the full session/middleware pattern.
412412

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

0 commit comments

Comments
 (0)