fix(router-core): harden string encoding/decoding boundaries by Sheraff · Pull Request #8141 · TanStack/router

Sheraff · 2026-08-21T21:46:21Z

Summary

Centralizes and hardens every string encoding/decoding surface in the router, guided by a full inventory (now maintained as packages/router-core/docs/string-handling.md).

Fix: URIError crash via route masks and `matchRoute`

Malformed percent-encoding in a URL segment (e.g. /post/%E4%BD, /post/%zz) made extractParams throw URIError. The main matcher (findRouteMatch) caught it, but findFlatMatch (route masks) and findSingleMatch (router.matchRoute) did not — such URLs crashed matching outright. findMatch is now the single choke point converting URIError into "no match" (404), which is byte-neutral vs. the previous per-caller guard and structurally prevents a future fourth entry point from re-introducing the bug. Behavior is otherwise unchanged: malformed sequences still 404; valid ones decode exactly as before.

Centralization + enforcement

New router-core/src/string-encoding.ts owns all URL-path primitives (decodePath, encodePathParam, compileDecodeCharMap, escapeHtml, ...) with trust-boundary docs
ESLint bans raw encodeURIComponent / decodeURI* / btoa / atob outside that module (documented exceptions for the matcher's no-match contract and ssr/serializer base64)
Branded string kinds (EncodedPathParam, DecodedPathParam, EncodedPath, DecodedPath) wired through real signatures — e.g. custom decoders are type-contracted to receive encoded values

Tests added (fast-check property-based + concrete regressions)

Surface	Coverage
Matcher	totality of all 3 entry points against arbitrary/hostile paths; encode→interpolate→decode→match round-trips; open-redirect defense
Search params	parse never throws; null prototypes always; JSON round-trip symmetry; `__proto__` safety
SSR inline scripts	adversarial scroll-restoration keys can't break `<script>` context and round-trip semantically; injected code provably never executes; seroval factory interpolation canary
Frame protocol	client frame-decoder (previously untested): exact round-trips, chunk-boundary independence, DoS caps (16MiB/frame etc.), fast-fail on hostile length headers
Server functions	GET payload size cap rejects before invoking the fn; malformed payloads → 500 not crash; method check before parsing; server context wins over client context
Build-time IDs	virtual-module base64url payload round-trips; distinct violations → distinct IDs; hostile payloads degrade to safe defaults
Early hints / prerender	Link-header param injection impossible outside quoted strings; protocol-relative prerender paths rejected

Documented quirks (deliberately not changed)

Legacy * splat syntax collision: splat value '*' interpolates to /files/* and resolves to the legacy route with empty params (reproduced; fix sketched in docs, needs e2e coverage)
Default search-param parser JSON-coerces values that look like JSON ('?q=%2042' → number)
Early-hints href is interpolated verbatim (manifest-controlled today)

Test plan

router-core: 110 files / 1663 tests pass (incl. new property suites)
start-client-core: 94 pass · start-server-core: 130 pass · start-plugin-core: 513 pass · react-router: 1036 pass
eslint clean (new boundary rules active), typecheck clean across TS versions
benchmarks: matcher module −40 raw bytes vs base; package-wide gzip net −165 incl. new module (tests/string-encoding.bench.ts)

Centralize all URL-path encoding/decoding primitives in a single string-encoding module with trust-boundary documentation, branded string kinds, and ESLint enforcement banning raw encodeURIComponent/ decodeURI*/btoa/atob elsewhere. Fixes a real crash: malformed percent-encoding (e.g. /post/%E4%BD) threw URIError out of extractParams through findFlatMatch (route masks) and findSingleMatch (router.matchRoute), which had no guard. findMatch is now the single choke point converting URIError into a null match (404), byte-neutral vs the previous per-caller guard. Adds fast-check property-based and concrete security tests for every encoding surface identified in docs/string-handling.md: - matcher totality, path param round-trips, open-redirect defense - search-param parse safety, null prototypes, JSON coercion contract - SSR inline-script XSS resistance (adversarial scroll-restoration keys) and seroval factory interpolation canary - frame protocol round-trips and client frame-decoder DoS limits - server-fn payload handling (size cap, method check, context merge, malformed input) - virtual-module base64url ID round-trips and hostile payload fallbacks - early-hints Link-header injection resistance and prerender SSRF Documents known quirks (legacy '*' splat collision, search-param JSON coercion, early-hints href interpolation) instead of silently changing behavior.

nx-cloud · 2026-08-21T21:46:48Z

View your CI Pipeline Execution ↗ for commit f7d2b85

Command	Status	Duration	Result
`nx affected --targets=test:eslint,test:unit,tes...`	❌ Failed	6m 18s	View ↗
`nx run-many --target=build --exclude=examples/*...`	✅ Succeeded	27s	View ↗

☁️ Nx Cloud last updated this comment at 2026-08-22 05:56:17 UTC

github-actions · 2026-08-21T21:47:47Z

🚀 Changeset Version Preview

7 package(s) bumped directly, 16 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
`@tanstack/react-router`	1.170.31 → 1.170.32	Changeset
`@tanstack/router-core`	1.171.26 → 1.171.27	Changeset
`@tanstack/solid-router`	1.170.29 → 1.170.30	Changeset
`@tanstack/start-client-core`	1.170.26 → 1.170.27	Changeset
`@tanstack/start-plugin-core`	1.171.38 → 1.171.39	Changeset
`@tanstack/start-server-core`	1.169.30 → 1.169.31	Changeset
`@tanstack/vue-router`	1.170.28 → 1.170.29	Changeset
`@tanstack/react-start`	1.168.48 → 1.168.49	Dependent
`@tanstack/react-start-client`	1.168.29 → 1.168.30	Dependent
`@tanstack/react-start-rsc`	0.1.47 → 0.1.48	Dependent
`@tanstack/react-start-server`	1.167.36 → 1.167.37	Dependent
`@tanstack/router-cli`	1.167.32 → 1.167.33	Dependent
`@tanstack/router-generator`	1.167.32 → 1.167.33	Dependent
`@tanstack/router-plugin`	1.168.34 → 1.168.35	Dependent
`@tanstack/router-vite-plugin`	1.167.34 → 1.167.35	Dependent
`@tanstack/solid-start`	1.168.46 → 1.168.47	Dependent
`@tanstack/solid-start-client`	1.168.28 → 1.168.29	Dependent
`@tanstack/solid-start-server`	1.167.35 → 1.167.36	Dependent
`@tanstack/start-static-server-functions`	1.167.31 → 1.167.32	Dependent
`@tanstack/start-storage-context`	1.167.28 → 1.167.29	Dependent
`@tanstack/vue-start`	1.168.45 → 1.168.46	Dependent
`@tanstack/vue-start-client`	1.167.31 → 1.167.32	Dependent
`@tanstack/vue-start-server`	1.167.35 → 1.167.36	Dependent

coderabbitai · 2026-08-21T21:48:00Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 64b8786d-c0cb-4f42-8858-ef6892e5d57b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

socket-security · 2026-08-21T21:48:19Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	fast-check@4.9.0

View full report

pkg-pr-new · 2026-08-21T21:50:42Z

More templates

@tanstack/arktype-adapter

npm i https://pkg.pr.new/@tanstack/arktype-adapter@8141

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@8141

@tanstack/eslint-plugin-start

npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@8141

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@8141

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/@tanstack/nitro-v2-vite-plugin@8141

@tanstack/react-router

npm i https://pkg.pr.new/@tanstack/react-router@8141

@tanstack/react-router-devtools

npm i https://pkg.pr.new/@tanstack/react-router-devtools@8141

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@8141

@tanstack/react-start

npm i https://pkg.pr.new/@tanstack/react-start@8141

@tanstack/react-start-client

npm i https://pkg.pr.new/@tanstack/react-start-client@8141

@tanstack/react-start-rsc

npm i https://pkg.pr.new/@tanstack/react-start-rsc@8141

@tanstack/react-start-server

npm i https://pkg.pr.new/@tanstack/react-start-server@8141

@tanstack/router-cli

npm i https://pkg.pr.new/@tanstack/router-cli@8141

@tanstack/router-core

npm i https://pkg.pr.new/@tanstack/router-core@8141

@tanstack/router-devtools

npm i https://pkg.pr.new/@tanstack/router-devtools@8141

@tanstack/router-devtools-core

npm i https://pkg.pr.new/@tanstack/router-devtools-core@8141

@tanstack/router-generator

npm i https://pkg.pr.new/@tanstack/router-generator@8141

@tanstack/router-plugin

npm i https://pkg.pr.new/@tanstack/router-plugin@8141

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@8141

@tanstack/router-utils

npm i https://pkg.pr.new/@tanstack/router-utils@8141

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/@tanstack/router-vite-plugin@8141

@tanstack/solid-router

npm i https://pkg.pr.new/@tanstack/solid-router@8141

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/@tanstack/solid-router-devtools@8141

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@8141

@tanstack/solid-start

npm i https://pkg.pr.new/@tanstack/solid-start@8141

@tanstack/solid-start-client

npm i https://pkg.pr.new/@tanstack/solid-start-client@8141

@tanstack/solid-start-server

npm i https://pkg.pr.new/@tanstack/solid-start-server@8141

@tanstack/start-client-core

npm i https://pkg.pr.new/@tanstack/start-client-core@8141

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/@tanstack/start-fn-stubs@8141

@tanstack/start-plugin-core

npm i https://pkg.pr.new/@tanstack/start-plugin-core@8141

@tanstack/start-server-core

npm i https://pkg.pr.new/@tanstack/start-server-core@8141

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/@tanstack/start-static-server-functions@8141

@tanstack/start-storage-context

npm i https://pkg.pr.new/@tanstack/start-storage-context@8141

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@8141

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@8141

@tanstack/vue-router

npm i https://pkg.pr.new/@tanstack/vue-router@8141

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/@tanstack/vue-router-devtools@8141

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@8141

@tanstack/vue-start

npm i https://pkg.pr.new/@tanstack/vue-start@8141

@tanstack/vue-start-client

npm i https://pkg.pr.new/@tanstack/vue-start-client@8141

@tanstack/vue-start-server

npm i https://pkg.pr.new/@tanstack/vue-start-server@8141

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@8141

commit: f7d2b85

github-actions · 2026-08-21T21:54:47Z

Bundle Size Benchmarks

Commit: d467717ac2b7
Measured at: 2026-08-22T05:51:11.851Z
Baseline source: history:d83a8964c250
Dashboard: bundle-size history

The following scenarios have bundle-size changes compared with the baseline:

Scenario	Current (gzip)	Initial (gzip)	Raw	Brotli	Trend
`react-router.minimal`	83.8 KiB -9 B	83.7 KiB -8 B	262.7 KiB -55 B	73.0 KiB -79 B	▆▃▃▁▁▅▅▅▃██▆
`react-router.full`	87.3 KiB -3 B	87.2 KiB -4 B	274.4 KiB -53 B	76.1 KiB +38 B	▅▃▃▁▁▇▇▇▄██▇
`solid-router.minimal`	33.2 KiB +4 B	33.1 KiB +4 B	96.6 KiB -41 B	30.0 KiB -3 B	▁▁▁▆▆▇▇▇▇███
`solid-router.full`	38.0 KiB +9 B	37.9 KiB +8 B	111.2 KiB -41 B	34.2 KiB -91 B	▁▁▁▆▆███▇▇▇█
`vue-router.minimal`	49.5 KiB -6 B	49.4 KiB -3 B	138.6 KiB -44 B	44.8 KiB +79 B	▁▁▁▂▂███▄▇▇▆
`vue-router.full`	55.1 KiB -9 B	55.0 KiB -8 B	156.8 KiB -41 B	49.6 KiB -6 B	▁▁▁▂▂███▄▇▇▅
`react-start.minimal`	96.7 KiB -3 B	96.6 KiB -3 B	305.0 KiB -41 B	83.8 KiB -52 B	▂▁▁▅▅▇▇▇▆███
`react-start.deferred-hydration`	97.5 KiB -2 B	96.6 KiB -5 B	306.4 KiB -41 B	84.5 KiB +14 B	▂▁▁▆▆▇▇▇▇███
`react-start.full`	99.9 KiB -6 B	99.8 KiB -6 B	314.7 KiB -64 B	86.6 KiB +43 B	▁▁▁▅▅▇▇▇▆███
`react-start.rsbuild.minimal`	100.1 KiB +2 B	99.9 KiB +2 B	315.3 KiB -37 B	86.4 KiB -48 B	▂▁▁▄▄███▆▇▇▇
`react-start.rsbuild.minimal-iife`	100.5 KiB +1 B	100.3 KiB +1 B	316.2 KiB -37 B	86.7 KiB +8 B	▂▁▁▄▄███▆▇▇▇
`react-start.rsbuild.full`	103.4 KiB -10 B	103.2 KiB -10 B	325.4 KiB -39 B	89.1 KiB +110 B	▂▁▁▄▄███▆▇▇▆
`solid-start.minimal`	46.0 KiB -2 B	45.9 KiB 0 B	137.7 KiB -43 B	41.0 KiB +38 B	▁▁▁▇▇███▇███
`solid-start.deferred-hydration`	49.1 KiB -7 B	46.0 KiB -5 B	145.2 KiB -39 B	43.7 KiB +9 B	▁▁▁▇▇███▇███
`solid-start.full`	51.1 KiB -4 B	51.0 KiB -4 B	153.1 KiB -41 B	45.3 KiB -5 B	▁▁▁▆▆▇▇▇▇███
`vue-start.minimal`	65.7 KiB -3 B	65.6 KiB -3 B	189.5 KiB -41 B	58.4 KiB -136 B	▁▁▁▆▆███▇███
`vue-start.full`	69.5 KiB -12 B	69.4 KiB -15 B	201.8 KiB -35 B	61.7 KiB -8 B	▁▁▁▆▆███▇██▇

Current gzip tracks all emitted client JS chunks. Initial gzip tracks only the entry/import graph. Trend sparkline is historical current gzip ending with this PR measurement; lower is better.

codspeed-hq · 2026-08-21T22:02:41Z

Merging this PR will regress 8 benchmarks

⚠️

Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 11 improved benchmarks
❌ 8 regressed benchmarks
✅ 161 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	`BASE`	`HEAD`	Efficiency
❌	Memory	`mem client mount-unmount (solid)`	481.8 KB	624.8 KB	-22.89%
❌	Memory	`mem server error-paths error (solid)`	978.9 KB	1,146.6 KB	-14.62%
❌	Memory	`mem server request-churn (solid)`	712.7 KB	809.8 KB	-11.98%
❌	Memory	`mem server server-fn-churn (vue)`	345.7 KB	373.7 KB	-7.49%
❌	Simulation	`client-nested-params navigation loop (react)`	211.1 ms	227.3 ms	-7.14%
❌	Memory	`mem client navigation-churn (solid)`	592.5 KB	627.7 KB	-5.61%
❌	Memory	`mem server aborted-requests (react)`	855.7 KB	899 KB	-4.82%
❌	Memory	`mem server error-paths redirect (vue)`	427.7 KB	448.2 KB	-4.56%
⚡	Memory	`mem server error-paths not-found (vue)`	2,304.3 KB	486.4 KB	×4.7
⚡	Memory	`mem server error-paths unmatched (react)`	544.1 KB	456.8 KB	+19.1%
⚡	Memory	`mem server aborted-requests (vue)`	1,110.1 KB	1,002.5 KB	+10.74%
⚡	Memory	`mem client unique-location-churn (vue)`	467.7 KB	427.2 KB	+9.46%
⚡	Memory	`mem server error-paths redirect (solid)`	382.2 KB	349.7 KB	+9.29%
⚡	Memory	`mem server error-paths not-found (react)`	423.7 KB	390.3 KB	+8.56%
⚡	Memory	`mem server error-paths redirect (react)`	318.9 KB	304.6 KB	+4.69%
⚡	Memory	`mem server peak-large-page (react)`	1.2 MB	1.2 MB	+4.49%
⚡	Memory	`mem server error-paths not-found (solid)`	557.9 KB	536.3 KB	+4.03%
⚡	Simulation	`client-async-pipeline navigation loop (react)`	107.1 ms	103 ms	+3.92%
⚡	Memory	`mem client interrupted-navigations (vue)`	368.7 KB	357.5 KB	+3.15%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

_{Comparing feat/string-encoding-hardening (f7d2b85) with main (d83a896)}

nx-cloud

Nx Cloud is proposing a fix for your failed CI:

We updated seven files introduced by this PR to resolve ESLint and TypeScript errors that prevented CI from passing. The fixes address import ordering, top-level type-only imports, a removed { maxKeys } option unsupported by fc.record(), AnySchema property access casts, a while (true) condition flagged by no-unnecessary-condition, a missing ViolationInfo required fields in makeViolation, a tuple-index error in prerender-ssrf.test.ts, and a missing AsyncLocalStorage import for TS 5.6 compatibility.

Tip

✅ We verified this fix by re-running @tanstack/start-client-core:test:eslint, @tanstack/router-core:test:eslint, @tanstack/start-server-core:test:types and 3 more.

Warning

The suggested diff is too large to display here, but you can view it on Nx Cloud ↗

Or Apply changes locally with:

npx nx-cloud apply-locally zkun-q8vg

Apply fix locally with your editor ↗ View interactive diff ↗

_{🎓 Learn more about Self-Healing CI on nx.dev}

github-actions Bot added package: router-core package: start-plugin-core package: start-server-core package: start-client-core labels Aug 21, 2026

This comment was marked as outdated.

Sign in to view

Merge branch 'main' into feat/string-encoding-hardening

f7d2b85

nx-cloud Bot reviewed Aug 22, 2026

View reviewed changes

Navigation Menu

Uh oh!

Uh oh!

fix(router-core): harden string encoding/decoding boundaries - #8141

fix(router-core): harden string encoding/decoding boundaries#8141
Sheraff wants to merge 2 commits into
mainfrom
feat/string-encoding-hardening

Sheraff commented Aug 21, 2026

Uh oh!

nx-cloud Bot commented Aug 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 21, 2026

Uh oh!

coderabbitai Bot commented Aug 21, 2026 •

edited

Loading

Review skipped

Uh oh!

socket-security Bot commented Aug 21, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Aug 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 21, 2026 •

edited

Loading

Uh oh!

codspeed-hq Bot commented Aug 21, 2026 •

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

nx-cloud Bot left a comment •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

Sheraff commented Aug 21, 2026

Summary

Fix: URIError crash via route masks and matchRoute

Centralization + enforcement

Tests added (fast-check property-based + concrete regressions)

Documented quirks (deliberately not changed)

Test plan

Uh oh!

nx-cloud Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 21, 2026

🚀 Changeset Version Preview

🟩 Patch bumps

Uh oh!

coderabbitai Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

socket-security Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Size Benchmarks

Uh oh!

codspeed-hq Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will regress 8 benchmarks

Performance Changes

Uh oh!

This comment was marked as outdated.

Uh oh!

nx-cloud Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Nx Cloud is proposing a fix for your failed CI:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Fix: URIError crash via route masks and `matchRoute`

nx-cloud Bot commented Aug 21, 2026 •

edited

Loading

coderabbitai Bot commented Aug 21, 2026 •

edited

Loading

socket-security Bot commented Aug 21, 2026 •

edited

Loading

pkg-pr-new Bot commented Aug 21, 2026 •

edited

Loading

github-actions Bot commented Aug 21, 2026 •

edited

Loading

codspeed-hq Bot commented Aug 21, 2026 •

edited

Loading

nx-cloud Bot left a comment •

edited

Loading