feat(clerk-js): Link to external App page in OAuth Consent (#6447)

In OAuthConsent wire the ApplicationLogo.href up to OAuth Application URL so that users can click the Logo of the OAuth App to navigate to the App's homepage.

Set isExternal to open the link in a new window and apply attribute rel="noopener noreferrer" to to avoid (in legacy browsers) passing an opener object to the target page, and to avoid sharing sensitive query string parameters.

Harden <Link> to not set href to dangerous URLs (e.g. from javascript: or data: protocols).

Test in sandbox http://localhost:4000/oauth-consent?app-url=https%3A%2F%2Fclerk.com&logo-url=http%3A%2F%2Flocalhost%3A3000%2Flogo

Part of USER-2011

Author: jfoshee

.changeset/sad-turkeys-rhyme.md

@@ -0,0 +1,10 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Add optional `isExternal` to `ApplicationLogo`
+
+Add optional `oAuthApplicationUrl` parameter to OAuth Consent mounting (which is used to provide a link to the OAuth App homepage).
+
+Harden `Link` component so it sanitizes the given `href` to avoid dangerous protocols.

.vscode/tasks.json

@@ -0,0 +1,13 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "type": "npm",
+      "script": "dev:sandbox",
+      "path": "packages/clerk-js",
+      "problemMatcher": [],
+      "label": "Dev: Sandbox",
+      "detail": "npm: dev:sandbox - packages/clerk-js"
+    }
+  ]
+}

packages/clerk-js/sandbox/app.ts

@@ -334,6 +334,8 @@ void (async () => {
           scopes,
           oAuthApplicationName: searchParams.get('oauth-application-name'),
           redirectUrl: searchParams.get('redirect_uri'),
+          oAuthApplicationLogoUrl: searchParams.get('logo-url'),
+          oAuthApplicationUrl: searchParams.get('app-url'),
         },
       );
     },

packages/clerk-js/src/ui/components/OAuthConsent/OAuthConsent.tsx

@@ -17,7 +17,7 @@ import { common } from '@/ui/styledSystem';
 import { colors } from '@/ui/utils/colors';
 
 export function OAuthConsentInternal() {
-  const { scopes, oAuthApplicationName, oAuthApplicationLogoUrl, redirectUrl, onDeny, onAllow } =
+  const { scopes, oAuthApplicationName, oAuthApplicationLogoUrl, oAuthApplicationUrl, redirectUrl, onDeny, onAllow } =
     useOAuthConsentContext();
   const { user } = useUser();
   const { applicationName, logoImageUrl } = useEnvironment().displayConfig;
@@ -46,6 +46,8 @@ export function OAuthConsentInternal() {
                   <ApplicationLogo
                     src={oAuthApplicationLogoUrl}
                     alt={oAuthApplicationName}
+                    href={oAuthApplicationUrl}
+                    isExternal
                   />
                 </ConnectionItem>
                 <ConnectionSeparator />
@@ -65,6 +67,8 @@ export function OAuthConsentInternal() {
                   <ApplicationLogo
                     src={oAuthApplicationLogoUrl}
                     alt={oAuthApplicationName}
+                    href={oAuthApplicationUrl}
+                    isExternal
                   />
                   <ConnectionIcon
                     size='sm'

packages/clerk-js/src/ui/elements/ApplicationLogo.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 
 import { useEnvironment } from '../contexts';
 import { descriptors, Flex, Image, useAppearance } from '../customizables';
+import { Link } from '../primitives';
 import type { PropsOfComponent } from '../styledSystem';
 import { RouterLink } from './RouterLink';
 
@@ -34,10 +35,16 @@ export type ApplicationLogoProps = PropsOfComponent<typeof Flex> & {
    * The URL to navigate to when the logo is clicked.
    */
   href?: string;
+  /**
+   * Whether the href should be treated as an external link.
+   * When true, uses a Link component with target="_blank" and proper security attributes.
+   * When false or undefined, uses RouterLink for internal navigation.
+   */
+  isExternal?: boolean;
 };
 
 export const ApplicationLogo: React.FC<ApplicationLogoProps> = (props: ApplicationLogoProps): JSX.Element | null => {
-  const { src, alt, href, sx, ...rest } = props;
+  const { src, alt, href, isExternal, sx, ...rest } = props;
   const imageRef = React.useRef<HTMLImageElement>(null);
   const [loaded, setLoaded] = React.useState(false);
   const { logoImageUrl, applicationName, homeUrl } = useEnvironment().displayConfig;
@@ -80,12 +87,22 @@ export const ApplicationLogo: React.FC<ApplicationLogoProps> = (props: Applicati
       ]}
     >
       {logoUrl ? (
-        <RouterLink
-          focusRing
-          to={logoUrl}
-        >
-          {image}
-        </RouterLink>
+        isExternal ? (
+          <Link
+            focusRing
+            href={logoUrl}
+            isExternal
+          >
+            {image}
+          </Link>
+        ) : (
+          <RouterLink
+            focusRing
+            to={logoUrl}
+          >
+            {image}
+          </RouterLink>
+        )
       ) : (
         image
       )}

packages/clerk-js/src/ui/primitives/Link.tsx

@@ -1,5 +1,6 @@
 import React from 'react';
 
+import { sanitizeHref } from '../../utils/url';
 import type { PrimitiveProps, StyleVariants } from '../styledSystem';
 import { common, createVariants } from '../styledSystem';
 import { applyDataStateProps } from './applyDataStateProps';
@@ -57,9 +58,12 @@ export type LinkProps = PrimitiveProps<'a'> & OwnProps & StyleVariants<typeof ap
 export const Link = (props: LinkProps): JSX.Element => {
   const { isExternal, children, href, onClick, ...rest } = props;
 
+  // Sanitize href to prevent dangerous protocols
+  const sanitizedHref = sanitizeHref(href);
+
   const onClickHandler = onClick
     ? (e: React.MouseEvent<HTMLAnchorElement, MouseEvent>) => {
-        if (!href) {
+        if (!sanitizedHref) {
           e.preventDefault();
         }
         onClick(e);
@@ -70,9 +74,9 @@ export const Link = (props: LinkProps): JSX.Element => {
     <a
       {...applyDataStateProps(filterProps(rest))}
       onClick={onClickHandler}
-      href={href || ''}
-      target={href && isExternal ? '_blank' : undefined}
-      rel={href && isExternal ? 'noopener' : undefined}
+      href={sanitizedHref || ''}
+      target={sanitizedHref && isExternal ? '_blank' : undefined}
+      rel={sanitizedHref && isExternal ? 'noopener noreferrer' : undefined}
       css={applyVariants(props) as any}
     >
       {children}

packages/clerk-js/src/utils/__tests__/url.spec.ts

@@ -7,6 +7,7 @@ import {
   createAllowedRedirectOrigins,
   getETLDPlusOneFromFrontendApi,
   getSearchParameterFromHash,
+  hasBannedHrefProtocol,
   hasBannedProtocol,
   hasExternalAccountSignUpError,
   isAllowedRedirect,
@@ -18,6 +19,7 @@ import {
   mergeFragmentIntoUrl,
   relativeToAbsoluteUrl,
   requiresUserInput,
+  sanitizeHref,
   trimLeadingSlash,
   trimTrailingSlash,
 } from '../url';
@@ -36,7 +38,7 @@ describe('isDevAccountPortalOrigin(url)', () => {
   ];
 
   test.each(goodUrls)('.isDevAccountPortalOrigin(%s)', (a, expected) => {
-    // @ts-ignore
+    // @ts-ignore - Type assertion for test parameter
     expect(isDevAccountPortalOrigin(a)).toBe(expected);
   });
 });
@@ -147,6 +149,79 @@ describe('hasBannedProtocol(url)', () => {
   });
 });
 
+describe('hasBannedHrefProtocol(url)', () => {
+  const cases: Array<[string, boolean]> = [
+    ['https://www.clerk.com/', false],
+    ['http://www.clerk.com/', false],
+    ['/sign-in', false],
+    ['/sign-in?test=1', false],
+    ['/?test', false],
+    ['javascript:console.log(document.cookies)', true],
+    ['data:image/png;base64,iVBORw0KGgoAAA5ErkJggg==', true],
+    ['vbscript:alert("xss")', true],
+    ['blob:https://example.com/12345678-1234-1234-1234-123456789012', true],
+    ['ftp://files.example.com/file.txt', false],
+    ['mailto:[email protected]', false],
+  ];
+
+  test.each(cases)('.hasBannedHrefProtocol(%s)', (a, expected) => {
+    expect(hasBannedHrefProtocol(a)).toBe(expected);
+  });
+});
+
+describe('sanitizeHref(href)', () => {
+  const cases: Array<[string | undefined | null, string | null]> = [
+    // Null/undefined/empty cases
+    [null, null],
+    [undefined, null],
+    ['', null],
+    ['     ', null],
+
+    // Safe relative URLs
+    ['/path/to/page', '/path/to/page'],
+    ['#anchor', '#anchor'],
+    ['?query=param', '?query=param'],
+    ['../relative/path', '../relative/path'],
+    ['relative/path', 'relative/path'],
+    ['path/page#anchor', 'path/page#anchor'],
+
+    // Safe absolute URLs
+    ['https://www.clerk.com/', 'https://www.clerk.com/'],
+    ['http://localhost:3000/path', 'http://localhost:3000/path'],
+    ['ftp://files.example.com/file.txt', 'ftp://files.example.com/file.txt'],
+    ['mailto:[email protected]', 'mailto:[email protected]'],
+
+    // Dangerous protocols - should return null
+    ['javascript:alert("xss")', null],
+    ['javascript:console.log(document.cookies)', null],
+    ['data:text/html,<script>alert("xss")</script>', null],
+    ['data:text/html;base64,PHNjcmlwdD5hbGVydCgnWFNTIGZyb20gZGF0YSBVUkknKTwvc2NyaXB0Pg==', null],
+    ['data:image/png;base64,iVBORw0KGgoAAA5ErkJggg==', null],
+    ['vbscript:alert("xss")', null],
+    ['blob:https://example.com/12345678-1234-1234-1234-123456789012', null],
+
+    // Sneaky cases with dangerous protocols
+    ['JAVASCRIPT:alert("xss")', null], // All caps protocol
+    ['JavaScript:alert("xss")', null], // Mixed case
+    ['  javascript:alert("xss")  ', null], // Whitespace
+    ['javascript: alert("xss")  ', null], // Whitespace
+
+    // Malformed URLs that might be relative paths
+    ['not-a-url', 'not-a-url'],
+    ['path:with:colons', 'path:with:colons'],
+  ];
+
+  test.each(cases)('.sanitizeHref(%s)', (href, expected) => {
+    expect(sanitizeHref(href)).toBe(expected);
+  });
+
+  it('handles malformed URLs gracefully', () => {
+    // These should not throw errors and should be allowed as potential relative URLs
+    expect(sanitizeHref(':::invalid:::')).toBe(':::invalid:::');
+    expect(sanitizeHref('malformed:url:here')).toBe('malformed:url:here');
+  });
+});
+
 describe('buildURL(options: URLParams, skipOrigin)', () => {
   it('builds a URL()', () => {
     expect(buildURL({}, { stringify: true })).toBe('http://localhost:3000/');

packages/clerk-js/src/utils/url.ts

@@ -21,6 +21,9 @@ const DUMMY_URL_BASE = 'http://clerk-dummy';
 
 const BANNED_URI_PROTOCOLS = ['javascript:'] as const;
 
+// Protocols that are dangerous specifically for href attributes in links
+const BANNED_HREF_PROTOCOLS = ['javascript:', 'data:', 'vbscript:', 'blob:'] as const;
+
 const { isDevOrStagingUrl } = createDevOrStagingUrlCache();
 export { isDevOrStagingUrl };
 const accountPortalCache = new Map<string, boolean>();
@@ -276,6 +279,16 @@ export function isDataUri(val?: string): val is string {
   return new URL(val).protocol === 'data:';
 }
 
+/**
+ * Checks if a URL uses javascript: protocol.
+ * This prevents some XSS attacks through javascript: URLs.
+ *
+ * IMPORTANT: This does not check for `data:` or other protocols which
+ * are dangerous if used for links or setting the window location.
+ *
+ * @param val - The URL to check
+ * @returns True if the URL contains a banned protocol, false otherwise
+ */
 export function hasBannedProtocol(val: string | URL) {
   if (!isValidUrl(val)) {
     return false;
@@ -284,6 +297,58 @@ export function hasBannedProtocol(val: string | URL) {
   return BANNED_URI_PROTOCOLS.some(bp => bp === protocol);
 }
 
+/**
+ * Checks if a URL contains a banned protocol for href attributes in links.
+ * This prevents some XSS attacks through javascript:, data:, vbscript:, and blob: URLs.
+ *
+ * @param val - The URL to check
+ * @returns True if the URL contains a banned protocol, false otherwise
+ */
+export function hasBannedHrefProtocol(val: string | URL): boolean {
+  if (!isValidUrl(val)) {
+    return false;
+  }
+  const protocol = new URL(val).protocol;
+  return BANNED_HREF_PROTOCOLS.some(bp => bp === protocol);
+}
+
+/**
+ * Sanitizes an href value by checking for dangerous protocols.
+ * Returns null if the href contains a dangerous protocol, otherwise returns the original href.
+ * This prevents some XSS attacks through javascript:, data:, vbscript:, and blob: URLs.
+ *
+ * @param href - The href value to sanitize
+ * @returns The sanitized href or null if dangerous
+ */
+export function sanitizeHref(href: string | undefined | null): string | null {
+  if (!href || href.trim() === '') {
+    return null;
+  }
+
+  // For relative URLs (starting with / or # or ?), allow them through
+  if (href.startsWith('/') || href.startsWith('#') || href.startsWith('?')) {
+    return href;
+  }
+
+  // For relative URLs without leading slash, allow them through
+  if (!href.includes(':')) {
+    return href;
+  }
+
+  // Check if it's a valid URL with a dangerous protocol
+  try {
+    const url = new URL(href);
+    if (hasBannedHrefProtocol(url)) {
+      return null;
+    }
+    return href;
+  } catch {
+    // If URL parsing fails, it's likely a relative URL or malformed
+    // Allow relative URLs through, but be cautious with malformed ones
+    return href;
+  }
+}
+
 export const hasUrlInFragment = (_url: URL | string) => {
   return new URL(_url, DUMMY_URL_BASE).hash.startsWith('#/');
 };

packages/types/src/clerk.ts

@@ -2002,6 +2002,10 @@ export type __internal_OAuthConsentProps = {
    * Logo URL of the OAuth application.
    */
   oAuthApplicationLogoUrl?: string;
+  /**
+   * URL of the OAuth application.
+   */
+  oAuthApplicationUrl?: string;
   /**
    * Scopes requested by the OAuth application.
    */