Validate a hash is legit when it links to its own page (#2183)

NWylynko · alexisintech · web-flow · commit 39c71cca3473 · 2025-04-15T05:10:09.000+08:00
Co-authored-by: Alexis Aguilar &lt;98043211+alexisintech@users.noreply.github.com&gt;
diff --git a/docs/account-portal/disable-account-portal.mdx b/docs/account-portal/disable-account-portal.mdx
@@ -10,7 +10,7 @@ To disable the Account Portal:
 
 1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page.
 1. Select the **Danger** tab.
-1. Select **Disable Account Portal**. You will not be able to select this button until you have [set up an authentication flow for your users](#customizing-your-sign-upsign-in-flow), as applying this setting will immediately result in a 404 for all Account Portal pages.
+1. Select **Disable Account Portal**. You will not be able to select this button until you have [set up an authentication flow for your users](#customize-your-sign-up-sign-in-flow), as applying this setting will immediately result in a 404 for all Account Portal pages.
 
 ## Customize your sign-up/sign-in flow
 
diff --git a/docs/authentication/social-connections/linkedin-oidc.mdx b/docs/authentication/social-connections/linkedin-oidc.mdx
@@ -49,7 +49,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   ### Create a LinkedIn application
 
   > [!TIP]
-  > If you already have a LinkedIn app you'd like to connect to Clerk, select your app from the [**My apps**](https://www.linkedin.com/developers/apps?appStatus=active) page in the LinkedIn Developer Portal and proceed to the [next step](#get-your-client-id-and-client-secret) in this tutorial.
+  > If you already have a LinkedIn app you'd like to connect to Clerk, select your app from the [**My apps**](https://www.linkedin.com/developers/apps?appStatus=active) page in the LinkedIn Developer Portal and proceed to the [next step](#set-the-client-id-and-primary-client-secret-in-the-clerk-dashboard) in this tutorial.
 
   1. On the homepage of the [LinkedIn Developer Portal](https://developer.linkedin.com/), select **Create app**. You'll be redirected to the **Create an app** form.
   1. Fill out the necessary information. Then, select **Create app**. You'll be redirected to the app's **Products** page.
diff --git a/docs/backend-requests/resources/session-tokens.mdx b/docs/backend-requests/resources/session-tokens.mdx
@@ -47,7 +47,7 @@ You can also create custom tokens using a [JWT template](/docs/backend-requests/
 
 The Clerk session token is stored in a cookie. All modern browsers [limit the maximum size of a cookie to 4kb](https://datatracker.ietf.org/doc/html/rfc2109#section-6.3). Exceeding this limit can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications.
 
-A session token with the [default session claims](#session-claims) won't run into this issue, as this configuration produces a cookie significantly smaller than 4kb. However, this limitation becomes relevant when implementing a [custom session token](/docs/backend-requests/custom-session-token). In this case, it's recommended to move particularly large claims out of the token and fetch these using a separate API call from your backend.
+A session token with the [default session claims](#default-claims) won't run into this issue, as this configuration produces a cookie significantly smaller than 4kb. However, this limitation becomes relevant when implementing a [custom session token](/docs/backend-requests/custom-session-token). In this case, it's recommended to move particularly large claims out of the token and fetch these using a separate API call from your backend.
 
 Claims to monitor for size limits:
 
diff --git a/docs/components/authentication/sign-up.mdx b/docs/components/authentication/sign-up.mdx
@@ -221,7 +221,7 @@ The following example includes basic implementation of the `<SignUp />` componen
     ---
 
     - `props?`
-    - [`SignUpProps`](#sign-up-props)
+    - [`SignUpProps`](#properties)
 
     The properties to pass to the `<SignUp />` component.
   </Properties>
@@ -299,7 +299,7 @@ The following example includes basic implementation of the `<SignUp />` componen
 
   <Properties>
     - `props?`
-    - [`SignUpProps`](#sign-up-props)
+    - [`SignUpProps`](#properties)
 
     The properties to pass to the `<SignUp />` component
   </Properties>
diff --git a/docs/custom-flows/email-links.mdx b/docs/custom-flows/email-links.mdx
@@ -24,7 +24,7 @@ This guide demonstrates how to use Clerk's API to build a custom flow for handli
 
 - [Sign up](#sign-up-flow)
 - [Sign in](#sign-in-flow)
-- [Verify a new email address](#email-address-verification-flow)
+- [Verify a new email address](#add-new-email-flow)
 
 <Steps>
   ## Enable email link authentication
diff --git a/docs/deployments/changing-domains.mdx b/docs/deployments/changing-domains.mdx
@@ -16,7 +16,7 @@ Learn how to change your Clerk production instance's domain or subdomain.
 1. Once you make the change to your domain, you will need to update the following:
    - Update DNS records
    - Generate new SSL certificates
-   - [Update your Publishable Key](#updating-your-publishable-key)
+   - [Update your Publishable Key](#update-your-publishable-key)
    - If using social connections, update the settings with your social connections so that the redirect URL they are using is correct.
    - If using JWT templates, update JWT issuer and JWKS Endpoint in external JWT SSO services.
 
diff --git a/docs/references/backend/types/auth-object.mdx b/docs/references/backend/types/auth-object.mdx
@@ -83,7 +83,7 @@ The `Auth` object contains important information like the current user's session
   ---
 
   - [`getToken()`](#get-token)
-  - [`ServerGetToken`](#server-get-token)
+  - `ServerGetToken`
 
   A function that gets the current user's [session token](/docs/backend-requests/resources/session-tokens) or a [custom JWT template](/docs/backend-requests/jwt-templates).
 
diff --git a/docs/references/chrome-extension/configure-consistent-crx-id.mdx b/docs/references/chrome-extension/configure-consistent-crx-id.mdx
@@ -58,7 +58,7 @@ To configure a consistent CRX ID for a new extension, follow these steps:
   1. Ensure that the development build is updated by running `pnpm dev`.
   1. Open Chrome or a Chromium-based browser and navigate to `chrome://extensions`.
   1. Remove and re-install the extension. To re-install, in the top-left, select **Load unpacked**. Navigate to where your project is located and select the `build/chrome-mv3-dev` folder. Then select **Select**. Your extension will now be loaded and shown in the list of extensions.
-  1. Confirm that the ID shown in your extension matches the CRX ID you saved [earlier](#configure-a-crx-id-for-a-new-extension).
+  1. Confirm that the ID shown in your extension matches the CRX ID you saved [earlier](#generate-your-keypairs).
 </Steps>
 
 ## For an extension uploaded to the Chrome Developer Dashboard
diff --git a/docs/references/javascript/sign-up.mdx b/docs/references/javascript/sign-up.mdx
@@ -8,7 +8,7 @@ The `SignUp` object holds the state of the current sign-up and provides helper m
 The following steps outline the sign-up process:
 
 1. Initiate the sign-up process by collecting the user's authentication information and passing the appropriate parameters to the [`create()`](#create) method.
-1. Prepare the [verification](#verification).
+1. Prepare the verification.
 1. Attempt to complete the verification.
 1. If the verification is successful, set the newly created session as the active session by passing the `SignIn.createdSessionId` to the [`setActive()`](/docs/references/javascript/clerk#set-active) method on the `Clerk` object.
 
diff --git a/docs/references/javascript/types/role.mdx b/docs/references/javascript/types/role.mdx
@@ -35,7 +35,7 @@ An interface that represents a role in an organization.
   ---
 
   - `permissions`
-  - <code>[PermissionResource](#permission-resource)\[]</code>
+  - <code>[PermissionResource](/docs/references/javascript/types/permission)\[]</code>
 
   The permissions of the role.
 
diff --git a/docs/references/nextjs/basic-rbac.mdx b/docs/references/nextjs/basic-rbac.mdx
@@ -66,7 +66,7 @@ This guide assumes that you're using Next.js App Router, but the concepts can be
   Create a helper function to simplify checking roles.
 
   1. In your application's root directory, create a `utils/` folder.
-  1. Inside this directory, create a `roles.ts` file with the following code. The `checkRole()` helper uses the [`auth()`](/docs/references/nextjs/auth) helper to access the user's session claims. From the session claims, it accesses the `metadata` object to check the user's role. The `checkRole()` helper accepts a role of type `Roles`, which you created in the [Create a global TypeScript definition](#create-a-global-typescript-definition) step. It returns `true` if the user has that role or `false` if they do not.
+  1. Inside this directory, create a `roles.ts` file with the following code. The `checkRole()` helper uses the [`auth()`](/docs/references/nextjs/auth) helper to access the user's session claims. From the session claims, it accesses the `metadata` object to check the user's role. The `checkRole()` helper accepts a role of type `Roles`, which you created in the [Create a global TypeScript definition](#create-a-global-type-script-definition) step. It returns `true` if the user has that role or `false` if they do not.
 
   ```ts {{ filename: 'utils/roles.ts' }}
   import { Roles } from '@/types/globals'
diff --git a/docs/references/nextjs/waitlist.mdx b/docs/references/nextjs/waitlist.mdx
@@ -107,7 +107,7 @@ In [**Waitlist** mode](/docs/authentication/configuration/restrictions#waitlist)
 
   To allow users to sign in once they've been approved from the waitlist, you must:
 
-  - [Add `clerkMiddleware()` to your app.](#add-clerkmiddleware-to-your-app)
+  - [Add `clerkMiddleware()` to your app.](#add-clerk-middleware-to-your-app)
   - [Add a sign-in page.](#add-a-sign-in-page)
 
   ### Add `clerkMiddleware()` to your app
diff --git a/docs/testing/playwright/test-authenticated-flows.mdx b/docs/testing/playwright/test-authenticated-flows.mdx
@@ -68,7 +68,7 @@ This guide demonstrates how to save the auth state globally and load it in your
 
   ## Load the stored auth state in your tests
 
-  You can either load the stored auth state [in the config](#-in-the-config) or directly [in a test file](#-in-a-test-file). Loading in the config is useful if you want to authenticate once and reuse the same auth state for all tests or groups of tests. Loading in a test file is useful if you want to authenticate for a specific test case.
+  You can either load the stored auth state [in the config](#in-the-config) or directly [in a test file](#in-a-test-file). Loading in the config is useful if you want to authenticate once and reuse the same auth state for all tests or groups of tests. Loading in a test file is useful if you want to authenticate for a specific test case.
 
   ### In the config
 
diff --git a/docs/testing/playwright/test-helpers.mdx b/docs/testing/playwright/test-helpers.mdx
@@ -35,9 +35,9 @@ Before calling `clerk.signIn()`, it is required to call `page.goto()` and naviga
   ---
 
   - `setupClerkTestingTokenOptions?`
-  - [`SetupClerkTestingTokenOptions`](#set-up-clerk-testing-token-options)
+  - [`SetupClerkTestingTokenOptions`](#setup-clerk-testing-token-options)
 
-  Options to pass to `setupClerkTestingToken()`. See [`SetupClerkTestingTokenOptions`](#set-up-clerk-testing-token-options).
+  Options to pass to `setupClerkTestingToken()`. See [`SetupClerkTestingTokenOptions`](#setup-clerk-testing-token-options).
 </Properties>
 
 #### `ClerkSignInParams`
diff --git a/docs/users/user-impersonation.mdx b/docs/users/user-impersonation.mdx
@@ -40,7 +40,7 @@ curl -X POST https://api.clerk.com/v1/actor_tokens -d '{ \
 }'
 ```
 
-When creating actor tokens, the object that you pass as the `actor` parameter will end up in the authentication token's `act` claim. You can read more details in the [JWT claims](#jwt-claims) section of this document.
+When creating actor tokens, the object that you pass as the `actor` parameter will end up in the authentication token's `act` claim. You can read more details in the [guide on session tokens](/docs/backend-requests/resources/session-tokens#default-claims).
 
 ### Revoke an actor token
 
diff --git a/scripts/build-docs.test.ts b/scripts/build-docs.test.ts
@@ -632,6 +632,68 @@ test`,
     expect(output).toContain(`warning Hash "my-heading" not found in /docs/page-2`)
     expect(output).toContain(`warning Doc /docs/page-3 not found`)
   })
+
+  test('Links with only a hash to the same page are valid', async () => {
+    const { tempDir } = await createTempFiles([
+      {
+        path: './docs/manifest.json',
+        content: JSON.stringify({
+          navigation: [[{ title: 'Page 1', href: '/docs/page-1' }]],
+        }),
+      },
+      {
+        path: './docs/page-1.mdx',
+        content: `---
+title: Page 1
+description: This is a test page
+---
+
+# Heading
+
+[Valid Link to self](#heading)`,
+      },
+    ])
+
+    const output = await build(
+      createConfig({
+        ...baseConfig,
+        basePath: tempDir,
+        validSdks: ['react'],
+      }),
+    )
+
+    expect(output).toBe('')
+  })
+
+  test('Invalid Links with only a hash to the same page should be reported', async () => {
+    const { tempDir } = await createTempFiles([
+      {
+        path: './docs/manifest.json',
+        content: JSON.stringify({
+          navigation: [[{ title: 'Page 1', href: '/docs/page-1' }]],
+        }),
+      },
+      {
+        path: './docs/page-1.mdx',
+        content: `---
+title: Page 1
+description: This is a test page
+---
+
+[Invalid Link to self](#invalid-heading)`,
+      },
+    ])
+
+    const output = await build(
+      createConfig({
+        ...baseConfig,
+        basePath: tempDir,
+        validSdks: ['react'],
+      }),
+    )
+
+    expect(output).toContain(`warning Hash "invalid-heading" not found in /docs/page-1`)
+  })
 })
 
 describe('Path and File Handling', () => {
diff --git a/scripts/build-docs.ts b/scripts/build-docs.ts
@@ -970,23 +970,28 @@ export const build = async (config: BuildConfig) => {
             if (node.type !== 'link') return
             if (!('url' in node)) return
             if (typeof node.url !== 'string') return
-            if (!node.url.startsWith('/docs/')) return
+            if (!node.url.startsWith('/docs/') && !node.url.startsWith('#')) return
             if (!('children' in node)) return
 
-            const [url, hash] = removeMdxSuffix(node.url).split('#')
+            let [url, hash] = removeMdxSuffix(node.url).split('#')
+
+            if (url === '') {
+              // If the link is just a hash, then we need to link to the same doc
+              url = doc.href
+            }
 
             const ignore = config.ignorePaths.some((ignoreItem) => url.startsWith(ignoreItem))
             if (ignore === true) return
 
-            const doc = docsMap.get(url)
+            const linkedDoc = docsMap.get(url)
 
-            if (doc === undefined) {
+            if (linkedDoc === undefined) {
               safeMessage(config, vfile, filePath, 'link-doc-not-found', [url], node.position)
               return
             }
 
             if (hash !== undefined) {
-              const hasHash = doc.headingsHashs.includes(hash)
+              const hasHash = linkedDoc.headingsHashs.includes(hash)
 
               if (hasHash === false) {
                 safeMessage(config, vfile, filePath, 'link-hash-not-found', [hash, url], node.position)
