@benjavicente/start-client-core 1.167.9 → 1.168.3

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 '@benjavicente/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 '@benjavicente/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 '@benjavicente/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 '@benjavicente/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 '@benjavicente/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 '@benjavicente/react-start'
+import { redirect } from '@benjavicente/react-router'
+import {
+  getRequestHeader,
+  setResponseHeader,
+} from '@benjavicente/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 '@benjavicente/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 '@benjavicente/react-start'
+import { getRequest } from '@benjavicente/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 '@benjavicente/react-start'
+import { getRequest } from '@benjavicente/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 '@benjavicente/<fw>-start/server-only'` | Mark whole file server-only | Import denied             | Allowed               |
+| `import '@benjavicente/<fw>-start/client-only'` | Mark whole file client-only | Allowed                   | Import denied         |
 
 ## Server-Only Execution
 
@@ -42,7 +45,7 @@ Understanding where code runs is fundamental to TanStack Start. This skill cover
 The primary way to run server-only code. On the client, calls become fetch requests:
 
 ```tsx
-// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+// Use @benjavicente/<framework>-start for your framework (react, solid, vue)
 import { createServerFn } from '@benjavicente/react-start'
 
 const fetchUser = createServerFn().handler(async () => {
@@ -59,7 +62,7 @@ const user = await fetchUser()
 For utility functions that must never run on client:
 
 ```tsx
-// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+// Use @benjavicente/<framework>-start for your framework (react, solid, vue)
 import { createServerOnlyFn } from '@benjavicente/react-start'
 
 const getSecret = createServerOnlyFn(() => process.env.DATABASE_URL)
@@ -73,7 +76,7 @@ const getSecret = createServerOnlyFn(() => process.env.DATABASE_URL)
 ### createClientOnlyFn
 
 ```tsx
-// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+// Use @benjavicente/<framework>-start for your framework (react, solid, vue)
 import { createClientOnlyFn } from '@benjavicente/react-start'
 
 const saveToStorage = createClientOnlyFn((key: string, value: string) => {
@@ -84,7 +87,7 @@ const saveToStorage = createClientOnlyFn((key: string, value: string) => {
 ### ClientOnly Component
 
 ```tsx
-// Use @tanstack/<framework>-router for your framework (react, solid, vue)
+// Use @benjavicente/<framework>-router for your framework (react, solid, vue)
 import { ClientOnly } from '@benjavicente/react-router'
 
 function Analytics() {
@@ -99,7 +102,7 @@ function Analytics() {
 ### useHydrated Hook
 
 ```tsx
-// Use @tanstack/<framework>-router for your framework (react, solid, vue)
+// Use @benjavicente/<framework>-router for your framework (react, solid, vue)
 import { useHydrated } from '@benjavicente/react-router'
 
 function TimeZoneDisplay() {
@@ -117,7 +120,7 @@ Behavior: SSR → `false`, first client render → `false`, after hydration →
 ## Environment-Specific Implementations
 
 ```tsx
-// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+// Use @benjavicente/<framework>-start for your framework (react, solid, vue)
 import { createIsomorphicFn } from '@benjavicente/react-start'
 
 const getDeviceInfo = createIsomorphicFn()
@@ -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 '@benjavicente/react-start/server-only'
+// (or @benjavicente/solid-start/server-only, @benjavicente/vue-start/server-only)
+
+export function getApiKey() {
+  return process.env.API_KEY
+}
+```
+
+```ts
+// src/lib/storage.ts
+import '@benjavicente/react-start/client-only'
+// (or @benjavicente/solid-start/client-only, @benjavicente/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 '@benjavicente/<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