@tanstack/start-client-core 1.168.1 → 1.168.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/start-client-core",
-  "version": "1.168.1",
+  "version": "1.168.2",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -69,19 +69,15 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "seroval": "^1.5.0",
-    "@tanstack/router-core": "1.169.1",
+    "seroval": "^1.5.4",
+    "@tanstack/router-core": "1.169.2",
     "@tanstack/start-fn-stubs": "1.161.6",
-    "@tanstack/start-storage-context": "1.166.34"
+    "@tanstack/start-storage-context": "1.166.35"
   },
   "devDependencies": {
-    "@tanstack/intent": "^0.0.14",
     "vite": "*",
     "@types/node": ">=20"
   },
-  "bin": {
-    "intent": "./bin/intent.js"
-  },
   "scripts": {
     "clean": "rimraf ./dist && rimraf ./coverage",
     "test": "pnpm test:eslint && pnpm test:types && pnpm test:build && pnpm test:unit",

package/skills/start-core/SKILL.md

@@ -24,13 +24,14 @@ TanStack Start is a full-stack React framework built on TanStack Router and Vite
 
 ## Sub-Skills
 
-| Task                                         | Sub-Skill                                                           |
-| -------------------------------------------- | ------------------------------------------------------------------- |
-| Type-safe RPCs, data fetching, mutations     | [start-core/server-functions/SKILL.md](./server-functions/SKILL.md) |
-| Request/function middleware, context, auth   | [start-core/middleware/SKILL.md](./middleware/SKILL.md)             |
-| Isomorphic execution, environment boundaries | [start-core/execution-model/SKILL.md](./execution-model/SKILL.md)   |
-| REST API endpoints alongside app routes      | [start-core/server-routes/SKILL.md](./server-routes/SKILL.md)       |
-| Hosting, SSR modes, prerendering, SEO        | [start-core/deployment/SKILL.md](./deployment/SKILL.md)             |
+| Task                                             | Sub-Skill                                                                       |
+| ------------------------------------------------ | ------------------------------------------------------------------------------- |
+| Type-safe RPCs, data fetching, mutations         | [start-core/server-functions/SKILL.md](./server-functions/SKILL.md)             |
+| Request/function middleware, context, auth       | [start-core/middleware/SKILL.md](./middleware/SKILL.md)                         |
+| Server-side auth: sessions, cookies, OAuth, CSRF | [start-core/auth-server-primitives/SKILL.md](./auth-server-primitives/SKILL.md) |
+| Isomorphic execution, environment boundaries     | [start-core/execution-model/SKILL.md](./execution-model/SKILL.md)               |
+| REST API endpoints alongside app routes          | [start-core/server-routes/SKILL.md](./server-routes/SKILL.md)                   |
+| Hosting, SSR modes, prerendering, SEO            | [start-core/deployment/SKILL.md](./deployment/SKILL.md)                         |
 
 ## Quick Decision Tree
 
@@ -41,6 +42,9 @@ Need to run code exclusively on the server (DB, secrets)?
 Need auth checks, logging, or shared logic across server functions?
   → start-core/middleware
 
+Need to add login, sessions, OAuth, CSRF, password reset?
+  → start-core/auth-server-primitives
+
 Need to understand where code runs (server vs client)?
   → start-core/execution-model
 

package/skills/start-core/auth-server-primitives/SKILL.md

@@ -0,0 +1,410 @@
+---
+name: start-core/auth-server-primitives
+description: >-
+  Server-side authentication primitives for TanStack Start: session
+  cookies (HttpOnly, Secure, SameSite, __Host- prefix), session
+  read/issue/destroy via createServerFn and middleware, OAuth
+  authorization-code flow with state and PKCE, password-reset
+  enumeration defense, CSRF for non-GET RPCs, rate limiting auth
+  endpoints, session rotation on privilege change. Pairs with
+  router-core/auth-and-guards for the routing side.
+type: sub-skill
+library: tanstack-start
+library_version: '1.166.2'
+requires:
+  - start-core
+  - start-core/server-functions
+  - start-core/middleware
+sources:
+  - TanStack/router:docs/start/framework/react/guide/authentication-overview.md
+  - TanStack/router:docs/start/framework/react/guide/authentication-server-primitives.md
+---
+
+# Auth Server Primitives
+
+This skill covers the **server half** of authentication: session storage, cookie issuance, OAuth flow, password-reset hardening, CSRF, rate limiting. For the **routing half** (`_authenticated` layout, `beforeLoad` redirects, RBAC checks), see [router-core/auth-and-guards](../../../../router-core/skills/router-core/auth-and-guards/SKILL.md).
+
+> **CRITICAL**: A route guard does NOT protect a `createServerFn` on that route. Server functions are RPC endpoints reachable by direct POST regardless of which route renders them. Auth must be enforced **inside the handler** (or via middleware), not on the calling route.
+> **CRITICAL**: Validating the _shape_ of a client-supplied identifier (`z.string().uuid().parse(...)`) is not authorization. A parsed UUID is still _some_ tenant — re-check membership against the session principal before using it.
+> **CRITICAL**: Read session/cookies inside `.handler()` or middleware `.server()`, not at module scope. Module-level reads run before requests exist (and are also undefined on Cloudflare Workers).
+
+## Session Cookies
+
+The recommended session storage is an HTTP-only cookie holding either an opaque session ID (with server-side lookup) or a signed/encrypted token. The cookie flags matter — set them all.
+
+```tsx
+// src/server/session.ts
+import {
+  getRequestHeader,
+  setResponseHeader,
+} from '@tanstack/react-start/server'
+
+const SESSION_COOKIE = '__Host-session' // __Host- prefix binds to the exact origin + path '/'
+const ONE_DAY = 60 * 60 * 24
+
+export function setSessionCookie(token: string) {
+  setResponseHeader(
+    'Set-Cookie',
+    [
+      `${SESSION_COOKIE}=${token}`,
+      `HttpOnly`, // not readable from JS — defeats XSS exfiltration
+      `Secure`, // HTTPS only (required for __Host- prefix)
+      `SameSite=Lax`, // sent on top-level navigations, blocks most CSRF
+      `Path=/`, // required for __Host- prefix
+      `Max-Age=${ONE_DAY}`,
+    ].join('; '),
+  )
+}
+
+export function clearSessionCookie() {
+  setResponseHeader(
+    'Set-Cookie',
+    `${SESSION_COOKIE}=; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=0`,
+  )
+}
+
+export function readSessionToken(): string | null {
+  const header = getRequestHeader('cookie')
+  if (!header) return null
+  for (const part of header.split(/;\s*/)) {
+    // Split only on the FIRST '=' — signed/base64 values often contain '='.
+    const eq = part.indexOf('=')
+    if (eq === -1) continue
+    if (part.slice(0, eq) === SESSION_COOKIE) return part.slice(eq + 1)
+  }
+  return null
+}
+```
+
+Flag rationale:
+
+- `HttpOnly` — JavaScript can't read the cookie, so an XSS bug can't steal the session.
+- `Secure` — HTTPS only. Required when using `__Host-` prefix.
+- `SameSite=Lax` — blocks CSRF on most cross-origin POST/PUT/DELETE. Use `Strict` for highest-security flows where loss of cross-site GET navigation is acceptable.
+- `__Host-` prefix — binds the cookie to the exact origin (no Domain attribute, Path must be `/`, Secure must be set). Prevents subdomain takeover from forging a session cookie.
+- `Path=/` — required by `__Host-`.
+- `Max-Age` — finite lifetime so a stolen cookie isn't useful forever. Pair with server-side session rotation.
+
+## Session Lookup as Middleware
+
+Use middleware to centralize session loading so every protected handler sees a typed session:
+
+```tsx
+// src/server/auth-middleware.ts
+import { createMiddleware } from '@tanstack/react-start'
+import { readSessionToken } from './session'
+
+export const authMiddleware = createMiddleware({ type: 'function' }).server(
+  async ({ next }) => {
+    const token = readSessionToken()
+    const session = token ? await db.sessions.findValid(token) : null
+    if (!session) throw new Error('Unauthorized')
+    return next({ context: { session } })
+  },
+)
+```
+
+Attach it to every server function that needs a logged-in user:
+
+```tsx
+import { createServerFn } from '@tanstack/react-start'
+import { authMiddleware } from '~/server/auth-middleware'
+
+export const getMyOrders = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    return db.orders.findMany({ where: { userId: context.session.userId } })
+  })
+```
+
+> **Route guards do not cover this.** A `createFileRoute('/_authenticated/orders')` with a `beforeLoad` redirect does NOT protect `getMyOrders` — the RPC is reachable via direct POST whether or not the user ever hits the route. Apply `authMiddleware` (or re-check inside `.handler()`) on every server function that needs auth.
+
+## Issuing a Session on Login
+
+```tsx
+// src/server/login.functions.ts
+import { createServerFn } from '@tanstack/react-start'
+import { z } from 'zod'
+import { setSessionCookie } from './session'
+
+export const login = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ email: z.string().email(), password: z.string() }))
+  .handler(async ({ data }) => {
+    const user = await db.users.findByEmail(data.email)
+    // Always run verifyPasswordHash — even when the user doesn't exist —
+    // so the user-not-found branch takes the same time as wrong-password.
+    // DUMMY_PASSWORD_HASH is a hash of any throwaway password computed once
+    // at startup with the same algorithm/cost as real password hashes.
+    const hashToCheck = user?.passwordHash ?? DUMMY_PASSWORD_HASH
+    const passwordMatches = await verifyPasswordHash(hashToCheck, data.password)
+    const ok = user != null && passwordMatches
+    if (!ok) throw new Error('Invalid email or password')
+
+    // ROTATE on privilege change: destroy any existing session, then issue fresh.
+    await db.sessions.revokeAllForUser(user.id)
+    const token = await db.sessions.create({ userId: user.id })
+    setSessionCookie(token)
+    return { ok: true }
+  })
+```
+
+## Logout
+
+```tsx
+import { createServerFn } from '@tanstack/react-start'
+import { authMiddleware } from '~/server/auth-middleware'
+import { clearSessionCookie } from '~/server/session'
+
+export const logout = createServerFn({ method: 'POST' })
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    await db.sessions.revoke(context.session.id)
+    clearSessionCookie()
+    return { ok: true }
+  })
+```
+
+## OAuth: state + PKCE
+
+For OAuth authorization-code flow, generate a one-time `state` (CSRF defense) and a PKCE verifier (defense against authorization-code interception). Store both in a short-lived signed cookie keyed to this exact login attempt.
+
+```tsx
+// src/server/oauth.functions.ts
+import { createServerFn } from '@tanstack/react-start'
+import { redirect } from '@tanstack/react-router'
+import {
+  getRequestHeader,
+  setResponseHeader,
+} from '@tanstack/react-start/server'
+import crypto from 'node:crypto'
+
+const OAUTH_STATE_COOKIE = '__Host-oauth' // expires fast; one-shot
+
+function base64url(buf: Buffer) {
+  return buf
+    .toString('base64')
+    .replace(/=/g, '')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+}
+
+export const startOAuth = createServerFn({ method: 'GET' }).handler(
+  async () => {
+    const state = base64url(crypto.randomBytes(32))
+    const verifier = base64url(crypto.randomBytes(32))
+    const challenge = base64url(
+      crypto.createHash('sha256').update(verifier).digest(),
+    )
+
+    setResponseHeader(
+      'Set-Cookie',
+      `${OAUTH_STATE_COOKIE}=${signed({ state, verifier })}; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=600`,
+    )
+
+    throw redirect({
+      href:
+        `https://provider.example/authorize` +
+        `?response_type=code` +
+        `&client_id=${process.env.OAUTH_CLIENT_ID}` +
+        `&redirect_uri=${encodeURIComponent(process.env.OAUTH_REDIRECT_URI!)}` +
+        `&state=${state}` +
+        `&code_challenge=${challenge}` +
+        `&code_challenge_method=S256`,
+    })
+  },
+)
+```
+
+In the callback handler, **verify the cookie state matches the returned state** and exchange the code with the verifier. If state is missing or doesn't match, abort — the request did not originate from your `startOAuth`.
+
+## Password Reset: defeat user enumeration
+
+When a user requests a reset, do not let the response shape or timing reveal whether the email is registered.
+
+```tsx
+import { createServerFn } from '@tanstack/react-start'
+import { z } from 'zod'
+
+export const requestPasswordReset = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ email: z.string().email() }))
+  .handler(async ({ data }) => {
+    const user = await db.users.findByEmail(data.email)
+    if (user) {
+      const token = await db.passwordResets.issue(user.id)
+      await sendResetEmail(user.email, token)
+    }
+    // Always 200, always the same body, regardless of whether the user exists.
+    // The user is told to check their inbox; no confirmation either way.
+    return { ok: true }
+  })
+```
+
+Do NOT:
+
+- Return 200 if exists, 404 if not.
+- Use a different message ("we sent you a link" vs "no account found").
+- Skip the work when the user doesn't exist (timing leak — measurable from the wire).
+
+## CSRF for non-GET RPCs
+
+`SameSite=Lax` on the session cookie blocks most cross-site CSRF for POST/PUT/DELETE. Two cases need extra defense:
+
+1. **Top-level GET navigation that mutates** — never do this. Always use POST/PUT/DELETE for mutations.
+2. **POST from a page on a sibling subdomain** — `SameSite=Lax` does NOT block this; verify the `Origin` header matches your app's origin in middleware.
+
+```tsx
+import { createMiddleware } from '@tanstack/react-start'
+import { getRequest } from '@tanstack/react-start/server'
+
+export const csrfMiddleware = createMiddleware().server(async ({ next }) => {
+  const request = getRequest()
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    const origin = request.headers.get('origin')
+    // Compare the FULL origin (scheme + host + port) — host alone lets
+    // http://example.com pass a check meant for https://example.com.
+    if (!origin || new URL(origin).origin !== process.env.APP_ORIGIN) {
+      throw new Error('Origin check failed')
+    }
+  }
+  return next()
+})
+```
+
+Attach this to global request middleware in `src/start.ts` so it covers every non-GET request, including server routes and SSR.
+
+## Rate Limiting Auth Endpoints
+
+A login endpoint without rate limiting is a credential-stuffing target. Limit per-IP (and ideally per-account) with a sliding window.
+
+```tsx
+import { createMiddleware } from '@tanstack/react-start'
+import { getRequest } from '@tanstack/react-start/server'
+
+function rateLimitMiddleware(opts: {
+  key: string
+  max: number
+  windowMs: number
+}) {
+  return createMiddleware().server(async ({ next }) => {
+    const request = getRequest()
+    const ip =
+      request.headers.get('cf-connecting-ip') ??
+      request.headers.get('x-forwarded-for')?.split(',')[0] ??
+      'unknown'
+    const bucketKey = `rl:${opts.key}:${ip}`
+    const allowed = await rateLimiter.consume(
+      bucketKey,
+      opts.max,
+      opts.windowMs,
+    )
+    if (!allowed) throw new Error('Too many requests')
+    return next()
+  })
+}
+
+// On the login server function:
+export const login = createServerFn({ method: 'POST' }).middleware([
+  rateLimitMiddleware({ key: 'login', max: 5, windowMs: 60_000 }),
+])
+// ...
+```
+
+## Session Rotation on Privilege Change
+
+Whenever the user's privileges change — login, logout, role change, password change — **destroy the old session and issue a new one**. This neutralizes session-fixation attacks where an attacker plants their own session ID in the victim's browser before login.
+
+```tsx
+// In the login handler (already shown above): destroy any pre-login session, then create a fresh one.
+await db.sessions.revokeAllForUser(user.id)
+const token = await db.sessions.create({ userId: user.id })
+setSessionCookie(token)
+```
+
+```tsx
+// On password change / role grant:
+await db.sessions.revokeAllForUser(user.id) // destroy existing
+const token = await db.sessions.create({ userId: user.id }) // issue fresh
+setSessionCookie(token)
+```
+
+## Common Mistakes
+
+### CRITICAL: Trusting the route guard for server-function auth
+
+```tsx
+// WRONG — the RPC is callable directly via POST regardless of the route
+export const Route = createFileRoute('/_authenticated/orders')({
+  beforeLoad: ({ context }) => {
+    if (!context.auth.isAuthenticated) throw redirect({ to: '/login' })
+  },
+})
+const getMyOrders = createServerFn({ method: 'GET' }).handler(async () => {
+  return db.orders.findMany() // ← anyone can hit the RPC and get all orders
+})
+
+// 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 } })
+  })
+```
+
+### CRITICAL: Treating shape validation as authorization
+
+A parsed UUID is _some_ workspace, not an _authorized_ workspace.
+
+```tsx
+// WRONG — UUID is well-formed but the user may not be a member
+const getWorkspaceData = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])
+  .inputValidator(z.object({ workspaceId: z.string().uuid() }))
+  .handler(async ({ context, data }) => {
+    return db.workspaces.findById(data.workspaceId) // missing membership check!
+  })
+
+// CORRECT — verify the session principal has access to that workspace
+const getWorkspaceData = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])
+  .inputValidator(z.object({ workspaceId: z.string().uuid() }))
+  .handler(async ({ context, data }) => {
+    const member = await db.memberships.find({
+      userId: context.session.userId,
+      workspaceId: data.workspaceId,
+    })
+    if (!member) throw new Error('Not a member of this workspace')
+    return db.workspaces.findById(data.workspaceId)
+  })
+```
+
+### HIGH: Returning different responses based on email existence
+
+Already covered above — `requestPasswordReset` must return the same body regardless of whether the email matches a user.
+
+### HIGH: Reading cookies/env at module scope
+
+```tsx
+// WRONG — module-load time, before any request exists
+const SESSION_SECRET = process.env.SESSION_SECRET
+export function signSession(payload) {
+  return sign(payload, SESSION_SECRET)
+}
+
+// CORRECT — read inside per-request callback
+export function signSession(payload) {
+  return sign(payload, process.env.SESSION_SECRET)
+}
+```
+
+On Cloudflare Workers and other edge runtimes, the module-level read evaluates to `undefined` even on the server because env is injected per-request. See [start-core/execution-model](../execution-model/SKILL.md).
+
+### MEDIUM: Long-lived sessions with no rotation
+
+A session token that never rotates is functionally a long-lived credential. Rotate on login, logout, password change, and role/permission change.
+
+## Cross-References
+
+- [router-core/auth-and-guards](../../../../router-core/skills/router-core/auth-and-guards/SKILL.md) — the routing side: `_authenticated` layout, `beforeLoad`, `redirect`, RBAC checks.
+- [start-core/server-functions](../server-functions/SKILL.md) — how to expose RPCs (and how the route guard does NOT cover them).
+- [start-core/middleware](../middleware/SKILL.md) — composing `authMiddleware` and others.
+- [start-core/execution-model](../execution-model/SKILL.md) — why module-level env/secret reads are wrong.

package/skills/start-core/deployment/SKILL.md

@@ -57,6 +57,15 @@ export default defineConfig({
 
 Deploy: `npx wrangler login && pnpm run deploy`
 
+> **Worker env is per-request.** Cloudflare Workers inject env vars at request time. `process.env.X` at module scope evaluates to `undefined` even on the server. The Cloudflare-canonical way to read env (including from module scope) is the `cloudflare:workers` env binding:
+>
+> ```ts
+> import { env } from 'cloudflare:workers'
+> const apiHost = env.API_HOST
+> ```
+>
+> Or read `process.env.X` per-request inside `.handler()` / middleware `.server()`. See [Cloudflare's environment-variables docs](https://developers.cloudflare.com/workers/configuration/environment-variables/) and [start-core/execution-model](../execution-model/SKILL.md).
+
 ### Netlify
 
 ```bash

package/skills/start-core/execution-model/SKILL.md

@@ -14,6 +14,7 @@ requires:
 sources:
   - TanStack/router:docs/start/framework/react/guide/execution-model.md
   - TanStack/router:docs/start/framework/react/guide/environment-variables.md
+  - TanStack/router:docs/start/framework/react/guide/import-protection.md
 ---
 
 # Execution Model
@@ -21,19 +22,21 @@ sources:
 Understanding where code runs is fundamental to TanStack Start. This skill covers the isomorphic execution model and how to control environment boundaries.
 
 > **CRITICAL**: ALL code in TanStack Start is isomorphic by default — it runs in BOTH server and client bundles. Route loaders run on BOTH server (during SSR) AND client (during navigation). Server-only operations MUST use `createServerFn`.
-> **CRITICAL**: Module-level `process.env` access runs in both environments. Secret values leak into the client bundle. Access secrets ONLY inside `createServerFn` or `createServerOnlyFn`.
+> **CRITICAL**: Module-level `process.env` access is wrong on **two** axes — security (values leak into the client bundle) AND runtime correctness (on Cloudflare Workers and other edge runtimes, env is injected per-request, so module-level reads evaluate to `undefined` even on the server). Read env inside `.handler()` or another per-request function, never at module scope.
 > **CRITICAL**: `VITE_` prefixed environment variables are exposed to the client bundle. Server secrets must NOT have the `VITE_` prefix.
 
 ## Execution Control APIs
 
-| API                      | Use Case                  | Client Behavior           | Server Behavior       |
-| ------------------------ | ------------------------- | ------------------------- | --------------------- |
-| `createServerFn()`       | RPC calls, data mutations | Network request to server | Direct execution      |
-| `createServerOnlyFn(fn)` | Utility functions         | Throws error              | Direct execution      |
-| `createClientOnlyFn(fn)` | Browser utilities         | Direct execution          | Throws error          |
-| `createIsomorphicFn()`   | Different impl per env    | Uses `.client()` impl     | Uses `.server()` impl |
-| `<ClientOnly>`           | Browser-only components   | Renders children          | Renders fallback      |
-| `useHydrated()`          | Hydration-dependent logic | `true` after hydration    | `false`               |
+| API                                         | Use Case                    | Client Behavior           | Server Behavior       |
+| ------------------------------------------- | --------------------------- | ------------------------- | --------------------- |
+| `createServerFn()`                          | RPC calls, data mutations   | Network request to server | Direct execution      |
+| `createServerOnlyFn(fn)`                    | Utility functions           | Throws error              | Direct execution      |
+| `createClientOnlyFn(fn)`                    | Browser utilities           | Direct execution          | Throws error          |
+| `createIsomorphicFn()`                      | Different impl per env      | Uses `.client()` impl     | Uses `.server()` impl |
+| `<ClientOnly>`                              | Browser-only components     | Renders children          | Renders fallback      |
+| `useHydrated()`                             | Hydration-dependent logic   | `true` after hydration    | `false`               |
+| `import '@tanstack/<fw>-start/server-only'` | Mark whole file server-only | Import denied             | Allowed               |
+| `import '@tanstack/<fw>-start/client-only'` | Mark whole file client-only | Allowed                   | Import denied         |
 
 ## Server-Only Execution
 
@@ -125,6 +128,45 @@ const getDeviceInfo = createIsomorphicFn()
   .client(() => ({ type: 'client', userAgent: navigator.userAgent }))
 ```
 
+## Import Protection: File Markers
+
+> Experimental.
+
+The `.server.*` and `.client.*` filename suffixes (e.g. `db.server.ts`) opt a file into Start's import protection — it can't be imported from the wrong environment. When you can't or don't want to rename the file, add a side-effect import at the top of the file to apply the same protection by marker:
+
+```ts
+// src/lib/secrets.ts (filename can't be *.server.ts)
+import '@tanstack/react-start/server-only'
+// (or @tanstack/solid-start/server-only, @tanstack/vue-start/server-only)
+
+export function getApiKey() {
+  return process.env.API_KEY
+}
+```
+
+```ts
+// src/lib/storage.ts
+import '@tanstack/react-start/client-only'
+// (or @tanstack/solid-start/client-only, @tanstack/vue-start/client-only)
+
+export function savePreferences(prefs: Record<string, string>) {
+  localStorage.setItem('prefs', JSON.stringify(prefs))
+}
+```
+
+Rules:
+
+- Both markers in the same file is an error.
+- Type-only imports are ignored (they erase to nothing at runtime).
+- Default behavior is `error` in production builds and `mock` in dev. The mock returns a recursive Proxy so dev keeps running while you fix the import graph.
+
+Pick the right tool:
+
+- File should never run on the wrong side **and** has no client API → `*.server.ts` filename or `import '@tanstack/<fw>-start/server-only'`.
+- One symbol needs to behave differently per environment → `createIsomorphicFn().client(...).server(...)`.
+- One function should error if called from the wrong side → `createServerOnlyFn` / `createClientOnlyFn`.
+- Component renders only after hydration → `<ClientOnly>` or `useHydrated()`.
+
 ## Environment Variables
 
 ### Server-Side (inside createServerFn)
@@ -229,22 +271,29 @@ export const Route = createFileRoute('/dashboard')({
 })
 ```
 
-### 2. CRITICAL: Exposing secrets via module-level process.env
+### 2. CRITICAL: Reading process.env at module scope
+
+Module-level `process.env` reads are wrong for **two** reasons, not one:
+
+1. **Security:** the value can be inlined into the client bundle, leaking secrets.
+2. **Runtime correctness (edge runtimes):** Cloudflare Workers and other edge SSR runtimes inject env at request time. Module-level code runs at module load, before the env exists, so the read evaluates to `undefined` even on the server. The bug only surfaces at deploy time.
 
 ```tsx
-// WRONG — runs in both environments, value in client bundle
+// WRONG — leaks to client AND is undefined on Workers
 const apiKey = process.env.SECRET_KEY
 export function fetchData() {
-  /* uses apiKey */
+  /* uses apiKey, which is undefined under Worker SSR */
 }
 
-// CORRECT — access inside server function only
+// CORRECT — read per-request, inside the handler
 const fetchData = createServerFn({ method: 'GET' }).handler(async () => {
   const apiKey = process.env.SECRET_KEY
   return fetch(url, { headers: { Authorization: apiKey } })
 })
 ```
 
+The same rule applies to middleware `.server()` callbacks, server-route handlers, and any function that runs per request — read env there, not at the top of the file.
+
 ### 3. CRITICAL: Using VITE\_ prefix for server secrets
 
 ```bash

package/skills/start-core/middleware/SKILL.md

@@ -21,7 +21,7 @@ sources:
 Middleware customizes the behavior of server functions and server routes. It is composable — middleware can depend on other middleware to form a chain.
 
 > **CRITICAL**: TypeScript enforces method order: `middleware()` → `inputValidator()` → `client()` → `server()`. Wrong order causes type errors.
-> **CRITICAL**: Client context sent via `sendContext` is NOT validated by default. If you send dynamic user-generated data, validate it in server-side middleware before use.
+> **CRITICAL**: Validating the _shape_ of `sendContext` (e.g. `z.string().uuid().parse(...)`) is NOT authorization. A parsed identifier is a well-formed identifier, not an authorized one. Always re-check access against the session principal before using a client-sent ID as a query key, filter, or path parameter.
 
 ## Two Types of Middleware
 
@@ -241,7 +241,11 @@ const authMiddleware = createMiddleware().server(async ({ next, request }) => {
   if (!session) throw new Error('Unauthorized')
   return next({ context: { session } })
 })
+```
+
+> **Attach `authMiddleware` to every `createServerFn` that needs auth.** Server functions are RPC endpoints — a route `beforeLoad` does NOT protect the RPC, only the route's UI. Pair every protected route with handler-level enforcement here. See [router-core/auth-and-guards](../../../../router-core/skills/router-core/auth-and-guards/SKILL.md) and [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md).
 
+```tsx
 type Permissions = Record<string, string[]>
 
 function authorizationMiddleware(permissions: Permissions) {
@@ -299,23 +303,50 @@ Fetch precedence (highest to lowest): call site → later middleware → earlier
 
 ## Common Mistakes
 
-### 1. HIGH: Trusting client sendContext without validation
+### 1. CRITICAL: Trusting client sendContext — shape check is not access check
+
+`sendContext` from a client middleware arrives on the server as untrusted client input. Most agents stop after parsing the shape with Zod and assume the value is safe. It isn't: a parsed UUID is _some_ workspace, not the requesting user's workspace. Without a membership check against the session principal, you've built a tenant-walking endpoint.
+
+**Layer 1 — WRONG (no validation):**
 
 ```tsx
-// WRONG — client can send arbitrary data
 .server(async ({ next, context }) => {
+  // SQL-injectable AND tenant-walkable
   await db.query(`SELECT * FROM workspace_${context.workspaceId}`)
   return next()
 })
+```
+
+**Layer 2 — STILL WRONG (shape only):**
 
-// CORRECT — validate before use
+```tsx
 .server(async ({ next, context }) => {
+  // Looks safe, isn't. UUID is well-formed but the user may not be a member.
   const workspaceId = z.string().uuid().parse(context.workspaceId)
   await db.query('SELECT * FROM workspaces WHERE id = $1', [workspaceId])
   return next()
 })
 ```
 
+**Layer 3 — CORRECT (shape AND access):**
+
+```tsx
+.middleware([authMiddleware]) // session loaded from cookie, NOT from sendContext
+.server(async ({ next, context }) => {
+  const workspaceId = z.string().uuid().parse(context.workspaceId)
+  // Verify the session principal can access this workspace.
+  const member = await db.memberships.find({
+    userId: context.session.userId,
+    workspaceId,
+  })
+  if (!member) throw new Error('Not a member of this workspace')
+  await db.query('SELECT * FROM workspaces WHERE id = $1', [workspaceId])
+  return next({ context: { workspaceId } })
+})
+```
+
+The session itself must come from a server-trusted source (the cookie + DB lookup in `authMiddleware`), never from `sendContext` — anything the client can send, the client can lie about. See [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md).
+
 ### 2. MEDIUM: Confusing request vs server function middleware
 
 Request middleware runs on ALL requests (SSR, routes, functions). Server function middleware runs only for `createServerFn` calls and has `.client()` method.
@@ -363,3 +394,5 @@ createMiddleware({ type: 'function' })
 
 - [start-core/server-functions](../server-functions/SKILL.md) — what middleware wraps
 - [start-core/server-routes](../server-routes/SKILL.md) — middleware on API endpoints
+- [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) — building the `authMiddleware` factory itself: session cookie reads, OAuth state, CSRF
+- [router-core/auth-and-guards](../../../../router-core/skills/router-core/auth-and-guards/SKILL.md) — routing-side guards (route `beforeLoad` does NOT protect server functions; pair guards with `authMiddleware` on every protected RPC)

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/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/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
-}