fix(shared,nextjs,astro,nuxt): normalize URL paths in createPathMatcher by nikosdouvlis · Pull Request #8310 · clerk/javascript

nikosdouvlis · 2026-04-15T14:09:20Z

Summary

Adds normalizePath to @clerk/shared which normalizes URL paths before route matching in createPathMatcher, preventing route protection bypass via malformed or non-canonical paths
Introduces MalformedURLError with a cross-bundle isMalformedURLError check; each framework middleware (Next.js, Astro, Nuxt) catches this and returns HTTP 400
Adds unit tests for normalizePath and createPathMatcher, plus integration tests for all three frameworks covering path normalization edge cases
Adds dedicated Next.js middleware integration tests for both App Router and Pages Router

Test plan

packages/shared pathMatcher unit tests pass
packages/nextjs clerkMiddleware unit tests pass
Integration tests: astro middleware (dev + prod), nuxt middleware, nextjs middleware (app router + pages router)
Verify non-canonical paths are correctly normalized before route matching
Verify malformed paths return 400

…tcher createPathMatcher now decodes percent-encoded characters before matching, preventing route protection bypass via encoded URLs (e.g. /api/%61dmin bypassing /api/admin). Malformed encodings return HTTP 400.

…leware

…ding expectation The nuxt middleware catches MalformedURLError and returns 400, not 404. Also run nuxt prepare after pkglab install since --ignore-scripts skips postinstall.

Collapse consecutive slashes (e.g. //api/admin -> /api/admin) before regex matching to prevent potential auth bypass via double-slash URLs.

…lformedURLError on client Switch from decodeURIComponent to decodeURI so reserved delimiters (%2F, %3F, %23) are preserved. This aligns matcher behavior with framework router semantics — %2F stays as a literal segment character rather than being decoded into a path separator. Catch MalformedURLError in Nuxt client createRouteMatcher to prevent uncaught exceptions during client-side navigation with malformed paths.

…URL bypass

Move percent-encoded URL, dot segment, and double slash bypass tests from dynamic-keys.test.ts into integration/tests/nextjs/middleware.test.ts to match the Astro and Nuxt test structure.

…ction

Catching MalformedURLError and returning false on the client side silently treats malformed URLs as unprotected routes, which is the wrong failure mode for a security check. Let the error propagate instead (fail closed).

coderabbitai · 2026-04-15T14:09:30Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 51b7b37e-69ac-45bb-b6f9-c1a3fb2c1df1

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch normalize-url-paths-core-2

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

changeset-bot · 2026-04-15T14:09:32Z

🦋 Changeset detected

Latest commit: 1d45fbf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 22 packages

Name	Type
@clerk/shared	Patch
@clerk/nextjs	Patch
@clerk/astro	Patch
@clerk/nuxt	Patch
@clerk/agent-toolkit	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/elements	Patch
@clerk/expo-passkeys	Patch
@clerk/clerk-expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/react-router	Patch
@clerk/clerk-react	Patch
@clerk/remix	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/themes	Patch
@clerk/types	Patch
@clerk/vue	Patch
@clerk/localizations	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-04-15T14:09:33Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Apr 15, 2026 2:33pm

pkg-pr-new · 2026-04-15T14:12:52Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@8310

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8310

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8310

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8310

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8310

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8310

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@8310

@clerk/clerk-expo

npm i https://pkg.pr.new/@clerk/clerk-expo@8310

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8310

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8310

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8310

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8310

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8310

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8310

@clerk/clerk-react

npm i https://pkg.pr.new/@clerk/clerk-react@8310

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8310

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@8310

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8310

@clerk/tanstack-react-start

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

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8310

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@8310

@clerk/types

npm i https://pkg.pr.new/@clerk/types@8310

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8310

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8310

commit: 9eeffdb

The astro-node template on release/core-2 uses 'astro check && astro build' as the build script. The dynamically added middleware file fails type checking with the older @clerk/astro@2.x types. Override with 'astro build' only, which is also what the main branch template uses.

jacekradko and others added 15 commits April 13, 2026 13:17

fix(shared,nextjs,astro,nuxt): decode percent-encoded URLs in path ma…

ff660d0

…tcher createPathMatcher now decodes percent-encoded characters before matching, preventing route protection bypass via encoded URLs (e.g. /api/%61dmin bypassing /api/admin). Malformed encodings return HTTP 400.

chore: add changeset for percent-encoded URL fix

a1189ff

test(nuxt): add unit test for MalformedURLError handling in clerkMidd…

20741e0

…leware

test(nextjs): separate percent-encoded URL tests into own describe block

ef0f149

test(nuxt): separate percent-encoded URL tests and fix malformed enco…

1f7cfdb

…ding expectation The nuxt middleware catches MalformedURLError and returns 400, not 404. Also run nuxt prepare after pkglab install since --ignore-scripts skips postinstall.

fix(shared): normalize double slashes in path matcher to prevent bypass

39568f5

Collapse consecutive slashes (e.g. //api/admin -> /api/admin) before regex matching to prevent potential auth bypass via double-slash URLs.

Add tests for encoded dot slash cases

0795bb0

test(nextjs): add Pages Router integration tests for percent-encoded …

06827ec

…URL bypass

refactor(integration): move Next.js middleware tests to dedicated file

9aaf6ca

Move percent-encoded URL, dot segment, and double slash bypass tests from dynamic-keys.test.ts into integration/tests/nextjs/middleware.test.ts to match the Astro and Nuxt test structure.

fix(integration): restore dynamic-keys.test.ts to original state

87cb44e

refactor(shared): extract normalizePath as independently testable fun…

7c37ef6

…ction

chore: update changeset description

229cc8c

chore: rename changeset file

f1a18ec

github-actions Bot added nextjs integration astro nuxt core-2 labels Apr 15, 2026

Ephem approved these changes Apr 15, 2026

View reviewed changes

vercel Bot deployed to Preview April 15, 2026 14:10 View deployment

vercel Bot deployed to Preview April 15, 2026 14:33 View deployment

nikosdouvlis merged commit 2c14f0e into release/core-2 Apr 15, 2026
41 of 42 checks passed

nikosdouvlis deleted the normalize-url-paths-core-2 branch April 15, 2026 14:33

clerk-cookie mentioned this pull request Apr 15, 2026

ci(repo): Version packages (Core 2) #8316

Merged

codity-review Bot mentioned this pull request Apr 17, 2026

chore(deps): bump @clerk/shared from 3.47.3 to 3.47.4 eliasnau/wt#49

Closed

nikosdouvlis mentioned this pull request May 26, 2026

feat(clerk-js,shared): Backport Session Minter SDK changes to core-2 #8643

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(shared,nextjs,astro,nuxt): normalize URL paths in createPathMatcher#8310

fix(shared,nextjs,astro,nuxt): normalize URL paths in createPathMatcher#8310
nikosdouvlis merged 16 commits into
release/core-2from
normalize-url-paths-core-2

nikosdouvlis commented Apr 15, 2026

Uh oh!

coderabbitai Bot commented Apr 15, 2026 •

edited

Loading

Review skipped

Uh oh!

changeset-bot Bot commented Apr 15, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Apr 15, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Apr 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

nikosdouvlis commented Apr 15, 2026

Summary

Test plan

Uh oh!

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

Uh oh!

Review skipped

Uh oh!

changeset-bot Bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Apr 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

coderabbitai Bot commented Apr 15, 2026 •

edited

Loading

changeset-bot Bot commented Apr 15, 2026 •

edited

Loading

vercel Bot commented Apr 15, 2026 •

edited

Loading