feat: add protected routes feature

docs/pages/configuration/authentication.md

@@ -9,6 +9,33 @@ If you use a managed authentication service, such as Auth0, Clerk or OpenID you
 
 To implement the authentication option for your site, add the `authentication` property to the [Zudoku Configuration](./overview.md) file. The configuration is slightly different depending on the authentication provider you use.
 
+## Protected Routes
+
+You can protect specific routes in your documentation by adding the `protectedRoutes` property to your configuration. This property takes an array of glob patterns that match the routes you want to protect. When a user tries to access a protected route without being authenticated, they will be redirected to the login page.
+
+```typescript
+{
+  // ...
+  protectedRoutes: [
+    "/admin/*",     // Protect all routes under /admin
+    "/settings",    // Protect the settings page
+    "/api/**",      // Protect all API-related routes
+    "/*.secret.*"   // Protect any route with 'secret' in the name
+  ],
+  // ...
+}
+```
+
+The glob patterns support the following special characters:
+
+- `*` matches any number of characters except `/`
+- `**` matches any number of characters including `/`
+- `?` matches a single character except `/`
+- `[...]` matches any character in the brackets
+- `{...}` matches any pattern in the braces
+
+After logging in, users will be automatically redirected back to the protected route they were trying to access.
+
 ### Auth0
 
 For Auth0, you will need the `clientId` associated with the domain you are using.

docs/pages/configuration/overview.md

@@ -29,6 +29,11 @@ const config: ZudokuConfig = {
       },
     ],
   },
+  // Protect specific routes that require authentication
+  protectedRoutes: [
+    "/admin/*", // Protect all routes under /admin
+    "/api/private", // Protect private API documentation
+  ],
   redirects: [{ from: "/", to: "/documentation" }],
   apis: {
     type: "url",

examples/with-auth0/zudoku.config.ts

@@ -3,7 +3,7 @@ import { type ZudokuConfig } from "zudoku";
 const config: ZudokuConfig = {
   topNavigation: [
     { id: "documentation", label: "Documentation" },
-    { id: "api", label: "Rick & Morty API" },
+    { id: "api", label: "Rick & Morty API", display: "auth" },
   ],
   sidebar: {
     documentation: [
@@ -14,6 +14,10 @@ const config: ZudokuConfig = {
       },
     ],
   },
+  protectedRoutes: [
+    "/documentation/installation",
+    "/api/**",
+  ],
   redirects: [{ from: "/", to: "/documentation/introduction" }],
   docs: {
     files: "/pages/**/*.mdx",

packages/zudoku/package.json

@@ -255,7 +255,8 @@
     "yargs": "17.7.2",
     "zod": "3.23.8",
     "zod-validation-error": "3.4.0",
-    "zustand": "5.0.2"
+    "zustand": "5.0.2",
+    "minimatch": "^9.0.0"
   },
   "devDependencies": {
     "@graphql-codegen/cli": "5.0.3",
@@ -279,7 +280,8 @@
     "react-dom": "catalog:",
     "rollup-plugin-visualizer": "5.12.0",
     "typescript": "5.7.2",
-    "vitest": "2.1.8"
+    "vitest": "2.1.8",
+    "@types/minimatch": "^5.1.2"
   },
   "peerDependencies": {
     "react": ">=19",

packages/zudoku/src/app/main.tsx

@@ -1,4 +1,4 @@
-import { type RouteObject } from "react-router";
+import { Outlet, type RouteObject } from "react-router";
 import { configuredApiKeysPlugin } from "virtual:zudoku-api-keys-plugin";
 import {
   configuredApiCatalogPlugins,
@@ -13,8 +13,9 @@ import { configuredSidebar } from "virtual:zudoku-sidebar";
 import "virtual:zudoku-theme.css";
 import { Layout, RouterError, Zudoku } from "zudoku/components";
 import type { ZudokuConfig } from "../config/config.js";
-import type { ZudokuContextOptions } from "../lib/core/ZudokuContext.js";
 import { isNavigationPlugin } from "../lib/core/plugins.js";
+import { ProtectedRoute } from "../lib/core/ProtectedRoute.js";
+import type { ZudokuContextOptions } from "../lib/core/ZudokuContext.js";
 
 export const convertZudokuConfigToOptions = (
   config: ZudokuConfig,
@@ -32,6 +33,7 @@ export const convertZudokuConfigToOptions = (
     !config.page?.logo?.src?.dark;
 
   return {
+    protectedRoutes: config.protectedRoutes,
     page: {
       ...config.page,
       logo: {
@@ -102,6 +104,11 @@ export const getRoutesByConfig = (config: ZudokuConfig): RouteObject[] => {
       ),
       children: [
         {
+          element: (
+            <ProtectedRoute>
+              <Outlet />
+            </ProtectedRoute>
+          ),
           errorElement: <RouterError />,
           children: routes,
         },

packages/zudoku/src/config/validators/common.ts

@@ -295,6 +295,7 @@ const ApiCatalogSchema = z.object({
  * formats.
  */
 export const CommonConfigSchema = z.object({
+  protectedRoutes: z.array(z.string()).optional(),
   basePath: z.string().optional(),
   page: PageSchema,
   topNavigation: z.array(TopNavigationItemSchema),

packages/zudoku/src/lib/core/ProtectedRoute.tsx

@@ -0,0 +1,45 @@
+import { minimatch } from "minimatch";
+import { useEffect } from "react";
+import { useLocation } from "react-router";
+import { useAuth } from "../authentication/hook.js";
+import { useZudoku } from "../components/context/ZudokuContext.js";
+import { ZudokuError } from "../util/invariant.js";
+
+export function isProtectedRoute(
+  path: string,
+  protectedPatterns?: string[],
+): boolean {
+  if (!protectedPatterns?.length) return false;
+  return protectedPatterns.some((pattern) => minimatch(path, pattern));
+}
+
+export function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const auth = useAuth();
+  const zudoku = useZudoku();
+  const location = useLocation();
+
+  const isProtected = isProtectedRoute(
+    location.pathname,
+    zudoku.options.protectedRoutes,
+  );
+
+  useEffect(() => {
+    if (isProtected && !auth.isAuthenticated) {
+      void zudoku.authentication?.signIn();
+    }
+  }, [isProtected, auth.isAuthenticated, zudoku.authentication]);
+
+  if (isProtected && !auth.isAuthenticated) {
+    return null;
+  }
+
+  if (isProtected && !auth.isAuthEnabled) {
+    throw new ZudokuError("Authentication is not enabled", {
+      title: "Authentication is not enabled",
+      developerHint:
+        "To use protectedRoutes you need authentication to be enabled",
+    });
+  }
+
+  return children;
+}

packages/zudoku/src/lib/core/ZudokuContext.ts

@@ -65,6 +65,7 @@ export type ZudokuContextOptions = {
     components?: MdxComponentsType;
   };
   overrides?: ComponentsContextType;
+  protectedRoutes?: string[];
 };
 
 export class ZudokuContext {
@@ -74,16 +75,16 @@ export class ZudokuContext {
   public meta: ZudokuContextOptions["metadata"];
   public page: ZudokuContextOptions["page"];
   public authentication?: ZudokuContextOptions["authentication"];
-  private navigationPlugins: NavigationPlugin[];
+  private readonly navigationPlugins: NavigationPlugin[];
 
-  constructor(config: ZudokuContextOptions) {
-    this.plugins = config.plugins ?? [];
-    this.topNavigation = config.topNavigation ?? [];
-    this.sidebars = config.sidebars ?? {};
+  constructor(public readonly options: ZudokuContextOptions) {
+    this.plugins = options.plugins ?? [];
+    this.topNavigation = options.topNavigation ?? [];
+    this.sidebars = options.sidebars ?? {};
     this.navigationPlugins = this.plugins.filter(isNavigationPlugin);
-    this.authentication = config.authentication;
-    this.meta = config.metadata;
-    this.page = config.page;
+    this.authentication = options.authentication;
+    this.meta = options.metadata;
+    this.page = options.page;
   }
 
   initialize = async (): Promise<void> => {