TanStack Router Type-Safe URL Search Parameter Canonicalization & Validation Invariant

--- description: TanStack Router Type-Safe URL Search Parameter Canonicalization & Validation Invariant - Enforces strict runtime structural validation and sanitization on all TanStack Router search parameters via validated schemas in the validateSearch hook. Prevents unvalidated search params from triggering open redirects, bypassing access controls, injecting script vectors into DOM sinks, or corrupting client-side state. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx}, routes/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-router-search-param-canonicalization" --- # TanStack Router Type-Safe URL Search Parameter Canonicalization & Validation Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Type Casting Unvalidated Search Params Leading to Client-Side State Injection and XSS Vulnerabilities ## System Constraints You are a Principal Software Architect enforcing TanStack Router Type-Safe URL Search Parameter Canonicalization Invariants. Mandate that every route accepting search parameters executes strict runtime schema validation via validateSearch with sanitization and safe default fallbacks. Forbid any unchecked TypeScript casts (e.g., 'as SearchParams'), reject direct interpolation of unvalidated parameters into navigation redirects or DOM sinks, and ensure unknown URL keys are stripped to prevent parameter pollution. ## Strict Guidelines - Engineers MUST ALWAYS bind a runtime schema parser (e.g., Zod, Valibot, or ArkType) to the 'validateSearch' option of route definitions. - Engineers MUST NOT bypass runtime validation using TypeScript type assertions ('as RouteSearch' or '<RouteSearch>rawSearch'). - Schemas MUST strip unknown keys or explicitly define allowed properties to prevent prototype contamination and HTTP parameter pollution attacks. - Engineers MUST canonicalize redirect targets and external URI search parameters by validating against an internal relative path regex or an explicit domain whitelist. - Components MUST access search parameters exclusively using the generated 'Route.useSearch()' or 'useSearch({ from: Route.fullPath })' hooks rather than window.location or raw query string parsing. - Schemas SHOULD provide fallback values via '.catch()' or '.default()' to gracefully recover from malformed user-supplied URLs without triggering unbounded error boundaries. ## Bad vs Good Implementations ### Type Assertion Bypass vs. Strict Zod Schema Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The route uses a blind TypeScript type cast inside validateSearch. Non-numeric query params produce runtime NaN errors, unknown keys pollute application state, and unvalidated URL strings allow DOM XSS through 'javascript:' pseudoprotocols. ```typescript import { createFileRoute } from '@tanstack/react-router'; interface DashboardSearch { page: number; filter: string; redirectUrl?: string; } // VULNERABILITY: Bypasses runtime validation; casts raw search input. // Malicious payloads (e.g. redirectUrl="javascript:alert(1)") pass through undetected. export const Route = createFileRoute('/dashboard')({ validateSearch: (search: Record<string, unknown>): DashboardSearch => { return search as unknown as DashboardSearch; }, component: DashboardComponent, }); function DashboardComponent() { const { page, redirectUrl } = Route.useSearch(); return ( <div> {/* DOM XSS vector via unvalidated URI scheme */} {redirectUrl && <a href={redirectUrl}>Continue</a>} <span>Page: {page + 1}</span> {/* Runtime NaN if page is not a number */} </div> ); } ``` #### Production Standard (Correct) > **Standard**: Search parameters are coerced and strictly parsed at runtime using Zod. Coerce and .catch() enforce safe defaults on malformed input, while redirectUrl enforces a strict regex preventing open redirects and script injection. ```typescript import { createFileRoute } from '@tanstack/react-router'; import { z } from 'zod'; // INVARIANT: Runtime schema enforces types, sanitizes redirects, and handles fallbacks. const safeRelativePathRegex = /^\/(?!\/)[a-zA-Z0-9_\-\.\/]*$/; const dashboardSearchSchema = z.object({ page: z.coerce.number().int().positive().catch(1), filter: z.string().trim().max(100).catch(''), redirectUrl: z .string() .regex(safeRelativePathRegex, 'Must be a safe internal relative path') .optional() .catch(undefined), }); export const Route = createFileRoute('/dashboard')({ validateSearch: (search) => dashboardSearchSchema.parse(search), component: DashboardComponent, }); function DashboardComponent() { const { page, redirectUrl } = Route.useSearch(); return ( <div> {redirectUrl && <a href={redirectUrl}>Continue</a>} <span>Page: {page}</span> </div> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Router Type-Safe URL Search Parameter Canonicalization & Validation Invariant

TanStack Router Type-Safe URL Search Parameter Canonicalization & Validation Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces strict runtime structural validation and sanitization on all TanStack Router search parameters via validated schemas in the validateSearch hook. Prevents unvalidated search params from triggering open redirects, bypassing access controls, injecting script vectors into DOM sinks, or corrupting client-side state. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Type Casting Unvalidated Search Params Leading to Client-Side State Injection and XSS Vulnerabilities Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Type Casting Unvalidated Search Params Leading to Client-Side State Injection and XSS Vulnerabilities	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS bind a runtime schema parser (e.g., Zod, Valibot, or ArkType) to the 'validateSearch' option of route definitions.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.