URIError: URI malformed - decodeURI in the clerk-js handshake aborts initialization on a malformed URL fragment

Open
#9,667 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
68/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
javascript, typescript
Domain
authentication, frontend

Research direction

Start in the clerk-js browser initialization and client handshake path, then reproduce the issue with the malformed URL fragment from the report. Verify that an undecodable fragment no longer aborts initialization, while valid fragments still allow the handshake and subsequent client requests to complete.

Written by the indexing model from the issue text.

Description

Preliminary Checks
  • I have reviewed the documentation: https://clerk.com/docs
  • I have searched for existing issues: https://github.com/clerk/javascript/issues
  • I have not already reached out to Clerk support via email or Discord
  • This issue is not a question, general help request, or anything other than a bug report directly related to Clerk
Reproduction

https://gist.github.com/RagDam/4a3098709c53c799c8351da0f586e0fe

Publishable key

Not included on purpose: the application is a private family tool. The bug reproduces with
any development instance - the failing call happens in the browser bundle, on a value read
from the current URL, before the instance matters. Happy to provide ours privately if it
helps.

Description

When the current URL carries a fragment that is not a valid percent-encoded sequence, for
example https://<app>/some-page#%E0%A4%A, clerk-js throws while initializing:

URIError: URI malformed
    at decodeURI (<anonymous>)
    at si (https://<instance>.clerk.accounts.dev/npm/@clerk/clerk-js@6/dist/clerk.browser.js:18:1587)

The call is decodeURI, on a value taken from the current URL, outside any try/catch.

Measured difference. Same page, same signed-in session, only the fragment differs:

Fragment Frontend API requests window.Clerk.session window.Clerk.user
#anything-valid GET /v1/client/handshake (307) x3, POST /v1/environment (200), GET /v1/client (200) active present
#%E0%A4%A GET /v1/client/handshake (307) x3, then nothing null null

Initialization stops at the handshake: /v1/environment and /v1/client are never
requested, so the client never gets a session.

Why this matters for end users. The session is never refreshed. The short-lived session
token expires (60 s in our development instance, exp - iat), and from then on every route
of the application shows the sign-in screen instead of the requested page. Signing in again
changes nothing, because the same fragment is still in the address bar. The user is locked
out with no way to relate this to the URL.

The input is not exotic: a truncated percent sequence is what a clipped copy-paste produces,
and what some mail clients do when they wrap a long link. Our application links to
/registre#<uuid> from e-mails and from an assistant answer, which is how we ran into it.

Expected. An unreadable fragment is not addressed to Clerk. Reading location.hash never
requires decoding, and decoding a value that comes from the URL should fail softly:
initialization should carry on and treat an undecodable fragment as an absent one.

This is the same class of bug as #9333 (ClerkRequest.parseCookies, malformed percent-escape
in the Cookie header), which was fixed in @clerk/backend. This one is the browser-side
counterpart, on the URL rather than on cookies, and is still present in clerk-js 6 as
loaded by @clerk/nextjs 7.9.1.

Workaround we shipped, an inline script in <head>, before the Clerk bundle runs:

!function () {
  function n() {
    try { decodeURIComponent(location.hash.slice(1)); }
    catch (e) { history.replaceState(null, "", location.pathname + location.search); }
  }
  n();
  addEventListener("hashchange", n);
}();

It removes the unreadable fragment before anything reads it, but every application would have
to know about this.

Environment
@clerk/nextjs: 7.9.1
@clerk/localizations: 4.16.0
clerk-js: 6 (loaded from the CDN as clerk.browser.js)
next: 16.3.4 (App Router, Turbopack)
node: 24.16.0
browser: Chromium 151.0.7922.34 (Playwright)
instance: development
Dominant language
TypeScript
Stars
1.8k
Forks
472
Avg merge
2d 8h
Merged PRs (30d)
184

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from clerk/javascript

All issues in clerk/javascript

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.