@tanstack/start-client-core 1.168.1 → 1.169.0

package/skills/start-core/server-functions/SKILL.md

@@ -19,6 +19,7 @@ sources:
 
 Server functions are type-safe RPCs created with `createServerFn`. They run exclusively on the server but can be called from anywhere — loaders, components, hooks, event handlers, or other server functions.
 
+> **CRITICAL**: Server functions are RPC endpoints. They are reachable by direct POST regardless of which route renders the calling UI. **Auth must be enforced inside the handler (or via middleware) — a route `beforeLoad` does NOT protect the RPC.** See [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) for the session/middleware pattern.
 > **CRITICAL**: Loaders are ISOMORPHIC — they run on BOTH client and server. Database queries, file system access, and secret API keys MUST go inside `createServerFn`, NOT in loaders directly.
 > **CRITICAL**: Do not use `"use server"` directives, `getServerSideProps`, or any Next.js/Remix server patterns. TanStack Start uses `createServerFn` exclusively.
 
@@ -199,16 +200,29 @@ import {
   setResponseStatus,
 } from '@tanstack/react-start/server'
 
-const getCachedData = createServerFn({ method: 'GET' }).handler(async () => {
-  const request = getRequest()
-  const authHeader = getRequestHeader('Authorization')
-
+// Public, non-personalized data — safe to cache shared across users.
+const getPublicData = createServerFn({ method: 'GET' }).handler(async () => {
   setResponseHeaders({
+    // 'public' is correct ONLY when the response does not depend on identity.
+    // For anything tied to a session/user/tenant, use 'private' or 'no-store'.
     'Cache-Control': 'public, max-age=300',
   })
   setResponseStatus(200)
+  return fetchPublicData()
+})
 
-  return fetchData()
+// Authenticated data — must NOT be 'public'.
+const getMyData = createServerFn({ method: 'GET' }).handler(async () => {
+  const authHeader = getRequestHeader('Authorization')
+  // ... auth check ...
+
+  setResponseHeaders({
+    // 'private' = only the user-agent may cache. Vary by Cookie/Authorization
+    // so any intermediary that does cache keys by identity, not URL alone.
+    'Cache-Control': 'private, max-age=60',
+    Vary: 'Cookie, Authorization',
+  })
+  return fetchPersonalizedData()
 })
 ```
 
@@ -254,7 +268,33 @@ Static imports of server functions are safe — the build replaces implementatio
 
 ## Common Mistakes
 
-### 1. CRITICAL: Putting server-only code in loaders
+### 1. CRITICAL: Relying on a route guard to protect a server function
+
+A `beforeLoad` redirect protects the **route's UI**, not the **RPC**. `createServerFn` exposes a callable endpoint that an attacker can hit directly — no need to load the route at all. Auth on the route is necessary but not sufficient.
+
+```tsx
+// WRONG — the route guard doesn't reach the handler
+const getMyOrders = createServerFn({ method: 'GET' }).handler(async () => {
+  return db.orders.findMany() // ← anyone can call the RPC
+})
+export const Route = createFileRoute('/_authenticated/orders')({
+  beforeLoad: ({ context }) => {
+    if (!context.auth.isAuthenticated) throw redirect({ to: '/login' })
+  },
+  loader: () => getMyOrders(),
+})
+
+// CORRECT — auth enforced on the handler itself
+const getMyOrders = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    return db.orders.findMany({ where: { userId: context.session.userId } })
+  })
+```
+
+Apply `authMiddleware` (or an equivalent in-handler check) to **every** `createServerFn` that needs auth. See [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) for the full session/middleware pattern and [start-core/middleware](../middleware/SKILL.md) for composing the factory.
+
+### 2. CRITICAL: Putting server-only code in loaders
 
 ```tsx
 // WRONG — loader is ISOMORPHIC, runs on BOTH client and server
@@ -276,22 +316,47 @@ export const Route = createFileRoute('/posts')({
 })
 ```
 
-### 2. CRITICAL: Using Next.js/Remix server patterns
+### 3. CRITICAL: Using Next.js / Remix / React Router DOM patterns
+
+If the file lives at `src/pages/`, `app/layout.tsx`, `_app/`, or imports anything from `react-router-dom` or `next/`, it is wrong-framework code. TanStack Start uses `src/routes/` + `createFileRoute` + `createServerFn`.
 
 ```tsx
 // WRONG — "use server" is a React directive, not used in TanStack Start
 'use server'
 export async function getUser() { ... }
 
-// WRONG — getServerSideProps is Next.js
+// WRONG — getServerSideProps is Next.js Pages Router
 export async function getServerSideProps() { ... }
 
-// CORRECT — TanStack Start uses createServerFn
+// WRONG — Next.js App Router server component data fetching
+export default async function Page() {
+  const data = await fetch(...).then(r => r.json())
+  return <div>{data}</div>
+}
+
+// WRONG — Remix
+export async function loader({ request }) { ... }
+export async function action({ request }) { ... }
+
+// WRONG — react-router-dom (a different library)
+import { Link, useNavigate } from 'react-router-dom'
+
+// CORRECT — TanStack Start
+import { createServerFn } from '@tanstack/react-start'
+import { Link, useNavigate, createFileRoute } from '@tanstack/react-router'
+
 const getUser = createServerFn({ method: 'GET' })
   .handler(async () => { ... })
+
+export const Route = createFileRoute('/users/$id')({
+  loader: ({ params }) => getUser({ data: { id: params.id } }),
+  component: UserPage,
+})
 ```
 
-### 3. HIGH: Dynamic imports for server functions
+If you see `src/pages/`, `app/layout.tsx`, or `react-router-dom` in agent output, the agent is generating for the wrong framework. Build will fail or routes will conflict at runtime.
+
+### 4. HIGH: Dynamic imports for server functions
 
 ```tsx
 // WRONG — can cause bundler issues
@@ -301,7 +366,7 @@ const { getUser } = await import('~/utils/users.functions')
 import { getUser } from '~/utils/users.functions'
 ```
 
-### 4. HIGH: Awaiting server function without calling it
+### 5. HIGH: Awaiting server function without calling it
 
 `createServerFn` returns a function — it must be invoked with `()`:
 
@@ -316,20 +381,53 @@ const data = await getItems()
 const data = await getItems({ data: { id: '1' } })
 ```
 
-### 5. MEDIUM: Not using useServerFn for component calls
+### 6. CRITICAL: Caching authenticated responses with `Cache-Control: public`
+
+`Cache-Control: public, max-age=N` tells every CDN, proxy, and shared cache between you and the user that this response can be served to anyone. If the response depends on the session (user, tenant, role), the first user's response gets cached and replayed to the next user — a cross-tenant data leak.
+
+```tsx
+// WRONG — auth'd response, public cache, leaks to next user via CDN
+const getMyOrders = createServerFn({ method: 'GET' }).handler(async () => {
+  const session = await requireSession() // identity-dependent
+  setResponseHeaders({ 'Cache-Control': 'public, max-age=300' })
+  return db.orders.findMany({ where: { userId: session.userId } })
+})
+
+// CORRECT — private + Vary so any cache that does store it keys by identity
+const getMyOrders = createServerFn({ method: 'GET' }).handler(async () => {
+  const session = await requireSession()
+  setResponseHeaders({
+    'Cache-Control': 'private, max-age=60',
+    Vary: 'Cookie, Authorization',
+  })
+  return db.orders.findMany({ where: { userId: session.userId } })
+})
+
+// ALSO CORRECT — opt out entirely for sensitive data
+setResponseHeaders({ 'Cache-Control': 'no-store' })
+```
+
+Rule of thumb: if the handler reads a session/cookie/auth header or branches on identity, the response is **not** `public`. Default to `private` (or `no-store` for sensitive data); reach for `public` only on responses that are byte-for-byte identical regardless of who asks. See also [start-core/deployment](../deployment/SKILL.md) for ISR/Cache-Control on full pages.
 
-When calling server functions from event handlers in components, use `useServerFn` to get proper React integration:
+### 7. MEDIUM: When to wrap with `useServerFn`
+
+`useServerFn` is **required** when the server function uses `throw redirect()` or `throw notFound()` — the hook wires the throw into the router so the redirect actually navigates. For server functions that just return data (call them directly or via `useMutation`/`useQuery`), the hook is optional.
 
 ```tsx
-// WRONG — direct call doesn't integrate with React lifecycle
+// Plain data — direct call is fine (also fine to pass to useMutation/useQuery)
 <button onClick={() => deletePost({ data: { id } })}>Delete</button>
+useMutation({ mutationFn: deletePost })
 
-// CORRECT — useServerFn integrates with React
-const deletePostFn = useServerFn(deletePost)
-<button onClick={() => deletePostFn({ data: { id } })}>Delete</button>
+// Throws redirect/notFound — MUST wrap with useServerFn so the router handles the throw
+const signupFn = useServerFn(signup) // signup throws redirect on success
+<button onClick={() => signupFn({ data: form })}>Sign up</button>
 ```
 
+If in doubt: wrap with `useServerFn`. It's a no-op for plain-data functions and the safe default when a function might later add a redirect.
+
 ## Cross-References
 
 - [start-core/execution-model](../execution-model/SKILL.md) — understanding where code runs
 - [start-core/middleware](../middleware/SKILL.md) — composing server functions with middleware
+- [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) — sessions, cookies, OAuth, CSRF, rate limiting (the server-side half of auth; `getCurrentUser`/`useSession`-style helpers belong here, not at module scope)
+- [router-core/auth-and-guards](../../../../router-core/skills/router-core/auth-and-guards/SKILL.md) — the routing side: route guards do NOT protect server functions, so always re-check auth in the handler or via middleware

package/src/createCsrfMiddleware.ts

@@ -0,0 +1,197 @@
+import { createIsomorphicFn } from '@tanstack/start-fn-stubs'
+import { createMiddleware } from './createMiddleware'
+import type {
+  RequestMiddlewareAfterServer,
+  RequestServerOptions,
+} from './createMiddleware'
+import type { Register } from '@tanstack/router-core'
+
+export const csrfSymbol = Symbol.for('tanstack-start:csrf-middleware')
+
+export type CsrfSecFetchSite =
+  | 'same-origin'
+  | 'same-site'
+  | 'cross-site'
+  | 'none'
+
+export type CsrfMatcher<TValue, TRegister = Register, TMiddlewares = unknown> =
+  | TValue
+  | Array<TValue>
+  | ((
+      value: TValue | (string & {}),
+      ctx: RequestServerOptions<TRegister, TMiddlewares>,
+    ) => boolean | Promise<boolean>)
+
+export interface CsrfMiddlewareOptions<
+  TRegister = Register,
+  TMiddlewares = unknown,
+> {
+  /**
+   * Return `true` to validate this request, or `false` to skip validation.
+   *
+   * @default undefined, which validates every request handled by this middleware.
+   */
+  filter?: (
+    ctx: RequestServerOptions<TRegister, TMiddlewares>,
+  ) => boolean | Promise<boolean>
+  /**
+   * Allowed Origin values. Defaults to the trusted request origin.
+   */
+  origin?: CsrfMatcher<string, TRegister, TMiddlewares>
+  /**
+   * Allowed Sec-Fetch-Site values.
+   *
+   * @default 'same-origin'
+   */
+  secFetchSite?: CsrfMatcher<CsrfSecFetchSite, TRegister, TMiddlewares>
+  /**
+   * Whether to use Referer as a fallback when Sec-Fetch-Site and Origin are absent.
+   *
+   * @default true
+   */
+  referer?:
+    | boolean
+    | ((
+        referer: string,
+        ctx: RequestServerOptions<TRegister, TMiddlewares>,
+      ) => boolean | Promise<boolean>)
+  /**
+   * Allow requests when Sec-Fetch-Site, Origin, and Referer are all missing.
+   *
+   * @default false
+   */
+  allowRequestsWithoutOriginCheck?: boolean
+  /**
+   * Optional response returned when CSRF validation fails.
+   *
+   * @default new Response('Forbidden', { status: 403 })
+   */
+  failureResponse?:
+    | Response
+    | ((
+        ctx: RequestServerOptions<TRegister, TMiddlewares>,
+      ) => Response | Promise<Response>)
+}
+
+type CreateCsrfMiddleware = <TRegister, TMiddlewares>(
+  opts?: CsrfMiddlewareOptions<TRegister, TMiddlewares>,
+) => RequestMiddlewareAfterServer<{}, undefined, undefined>
+
+const innerCreateCsrfMiddleware: CreateCsrfMiddleware = (opts = {}) => {
+  const middleware = createMiddleware().server(async (ctx) => {
+    const csrfCtx = ctx as RequestServerOptions<any, any>
+
+    if (opts.filter && !(await opts.filter(csrfCtx))) {
+      return ctx.next()
+    }
+
+    if (await isCsrfRequestAllowed(opts, csrfCtx)) {
+      return ctx.next()
+    }
+
+    return getFailureResponse(opts, csrfCtx)
+  })
+
+  if (process.env.NODE_ENV !== 'production') {
+    Object.defineProperty(middleware, csrfSymbol, { value: true })
+  }
+
+  return middleware
+}
+
+export const createCsrfMiddleware: CreateCsrfMiddleware =
+  createIsomorphicFn().server(innerCreateCsrfMiddleware) as CreateCsrfMiddleware
+
+export async function isCsrfRequestAllowed<TRegister, TMiddlewares>(
+  opts: CsrfMiddlewareOptions<TRegister, TMiddlewares>,
+  ctx: RequestServerOptions<TRegister, TMiddlewares>,
+): Promise<boolean> {
+  const result = await getCsrfRequestValidationResult(opts, ctx)
+  return (
+    result === true ||
+    (result === undefined && opts.allowRequestsWithoutOriginCheck === true)
+  )
+}
+
+export async function getCsrfRequestValidationResult<TRegister, TMiddlewares>(
+  opts: CsrfMiddlewareOptions<TRegister, TMiddlewares>,
+  ctx: RequestServerOptions<TRegister, TMiddlewares>,
+): Promise<boolean | undefined> {
+  const fetchSite = ctx.request.headers.get('Sec-Fetch-Site')
+  if (fetchSite !== null) {
+    return matchValue(opts.secFetchSite ?? 'same-origin', fetchSite, ctx)
+  }
+
+  const origin = ctx.request.headers.get('Origin')
+  if (origin !== null) {
+    if (opts.origin) {
+      return matchValue(opts.origin, origin, ctx)
+    }
+
+    return origin === new URL(ctx.request.url).origin
+  }
+
+  const referer = ctx.request.headers.get('Referer')
+  if (referer === null || opts.referer === false) {
+    return undefined
+  }
+
+  if (typeof opts.referer === 'function') {
+    return opts.referer(referer, ctx)
+  }
+
+  if (opts.origin) {
+    const refererOrigin = getOriginFromUrl(referer)
+    return (
+      refererOrigin !== undefined && matchValue(opts.origin, refererOrigin, ctx)
+    )
+  }
+
+  return isRefererSameOrigin(referer, new URL(ctx.request.url).origin)
+}
+
+async function matchValue<TValue extends string, TRegister, TMiddlewares>(
+  matcher: CsrfMatcher<TValue, TRegister, TMiddlewares>,
+  value: string,
+  ctx: RequestServerOptions<TRegister, TMiddlewares>,
+): Promise<boolean> {
+  if (typeof matcher === 'function') {
+    return matcher(value, ctx)
+  }
+
+  if (Array.isArray(matcher)) {
+    // typescript is dumb for array.includes()
+    return matcher.includes(value as TValue)
+  }
+
+  return value === matcher
+}
+
+function getOriginFromUrl(url: string): string | undefined {
+  try {
+    return new URL(url).origin
+  } catch {
+    return undefined
+  }
+}
+
+function isRefererSameOrigin(referer: string, requestOrigin: string): boolean {
+  if (referer === requestOrigin) return true
+  if (!referer.startsWith(requestOrigin)) return false
+  if (referer.length === requestOrigin.length) return true
+  const code = referer.charCodeAt(requestOrigin.length)
+  return code === 47 /* '/' */ || code === 63 /* '?' */ || code === 35 /* '#' */
+}
+
+async function getFailureResponse<TRegister, TMiddlewares>(
+  opts: CsrfMiddlewareOptions<TRegister, TMiddlewares>,
+  ctx: RequestServerOptions<TRegister, TMiddlewares>,
+): Promise<Response> {
+  if (typeof opts.failureResponse === 'function') {
+    return opts.failureResponse(ctx)
+  }
+
+  return (
+    opts.failureResponse?.clone() ?? new Response('Forbidden', { status: 403 })
+  )
+}

package/src/createMiddleware.ts

@@ -770,6 +770,10 @@ export interface RequestServerOptions<TRegister, TMiddlewares> {
   pathname: string
   context: Expand<AssignAllServerRequestContext<TRegister, TMiddlewares>>
   next: RequestServerNextFn<TRegister, TMiddlewares>
+  /**
+   * Type of Start handler currently processing this request.
+   */
+  handlerType: 'serverFn' | 'router'
   /**
    * Metadata about the server function being invoked.
    * This is only present when the request is handling a server function call.

package/src/index.tsx

@@ -84,6 +84,17 @@ export {
   flattenMiddlewares,
   executeMiddleware,
 } from './createServerFn'
+export {
+  createCsrfMiddleware,
+  csrfSymbol,
+  getCsrfRequestValidationResult,
+  isCsrfRequestAllowed,
+} from './createCsrfMiddleware'
+export type {
+  CsrfMatcher,
+  CsrfMiddlewareOptions,
+  CsrfSecFetchSite,
+} from './createCsrfMiddleware'
 
 export {
   TSS_FORMDATA_CONTEXT,

package/src/start-entry.d.ts

@@ -1,11 +1,11 @@
 declare module '#tanstack-start-entry' {
-  import type { StartEntry } from '@tanstack/start-client-core'
+  import type { StartEntry } from './startEntry'
 
   export const startInstance: StartEntry['startInstance']
 }
 
 declare module '#tanstack-router-entry' {
-  import type { RouterEntry } from '@tanstack/start-client-core'
+  import type { RouterEntry } from './startEntry'
 
   export const getRouter: RouterEntry['getRouter']
 }

package/src/tests/createServerMiddleware.test-d.ts

@@ -675,6 +675,7 @@ test('createMiddleware with type request, no middleware or context', () => {
       next: RequestServerNextFn<{}, undefined>
       pathname: string
       context: undefined
+      handlerType: 'serverFn' | 'router'
       serverFnMeta?: ServerFnMeta
     }>()
 
@@ -698,6 +699,7 @@ test('createMiddleware with type request, no middleware with context', () => {
       next: RequestServerNextFn<{}, undefined>
       pathname: string
       context: undefined
+      handlerType: 'serverFn' | 'router'
       serverFnMeta?: ServerFnMeta
     }>()
 
@@ -722,6 +724,7 @@ test('createMiddleware with type request, middleware and context', () => {
         next: RequestServerNextFn<{}, undefined>
         pathname: string
         context: undefined
+        handlerType: 'serverFn' | 'router'
         serverFnMeta?: ServerFnMeta
       }>()
 
@@ -746,6 +749,7 @@ test('createMiddleware with type request, middleware and context', () => {
         next: RequestServerNextFn<{}, undefined>
         pathname: string
         context: { a: string }
+        handlerType: 'serverFn' | 'router'
         serverFnMeta?: ServerFnMeta
       }>()
 
@@ -769,6 +773,7 @@ test('createMiddleware with type request can return Response directly', () => {
       next: RequestServerNextFn<{}, undefined>
       pathname: string
       context: undefined
+      handlerType: 'serverFn' | 'router'
       serverFnMeta?: ServerFnMeta
     }>()
 
@@ -789,6 +794,7 @@ test('createMiddleware with type request can return Promise<Response>', () => {
       next: RequestServerNextFn<{}, undefined>
       pathname: string
       context: undefined
+      handlerType: 'serverFn' | 'router'
       serverFnMeta?: ServerFnMeta
     }>()
 
@@ -804,6 +810,7 @@ test('createMiddleware with type request can return sync Response', () => {
       next: RequestServerNextFn<{}, undefined>
       pathname: string
       context: undefined
+      handlerType: 'serverFn' | 'router'
       serverFnMeta?: ServerFnMeta
     }>()
 

package/bin/intent.js

@@ -1,25 +0,0 @@
-#!/usr/bin/env node
-// Auto-generated by @tanstack/intent setup
-// Exposes the intent end-user CLI for consumers of this library.
-// Commit this file, then add to your package.json:
-//   "bin": { "intent": "./bin/intent.js" }
-try {
-  await import('@tanstack/intent/intent-library')
-} catch (e) {
-  const isModuleNotFound =
-    e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND'
-  const missingIntentLibrary =
-    typeof e?.message === 'string' && e.message.includes('@tanstack/intent')
-
-  if (isModuleNotFound && missingIntentLibrary) {
-    console.error('@tanstack/intent is not installed.')
-    console.error('')
-    console.error('Install it as a dev dependency:')
-    console.error('  npm add -D @tanstack/intent')
-    console.error('')
-    console.error('Or run directly:')
-    console.error('  npx @tanstack/intent@latest list')
-    process.exit(1)
-  }
-  throw e
-}