# Protected Routes

You can protect specific routes in your documentation by adding the `protectedRoutes` property to
your [Zudoku configuration](./overview.md). This requires [authentication](./authentication.md) to
be configured. The property supports two formats: a simple array of path patterns, or an advanced
object format with custom authorization logic.

:::note{title="SSR vs SSG protection"}

In **SSR mode**, `protectedRoutes` is enforced both client-side (login dialog) and at the bundle
level. Chunks containing content for protected routes are isolated into a separate, auth-gated
directory and never served to unauthenticated clients. See the
[Server-side Content Protection guide](../guides/server-side-content-protection.md) for the full
mechanics and caveats.

In **SSG mode** there is no server, so `protectedRoutes` is client-side only. The JavaScript chunks
for protected routes are still fetchable by anyone who knows the URL. Don't rely on SSG
`protectedRoutes` to hide sensitive information.

:::

## Array Format

The simplest way to protect routes is to provide an array of path patterns. Users must be
authenticated to access these routes.

```typescript title="zudoku.config.ts"
{
  // ...
  protectedRoutes: [
    "/admin/*",     // Protect all routes under /admin
    "/settings",    // Protect the settings page
    "/api/*",       // Protect all API-related routes
    "/private/:id"  // Protect dynamic routes with parameters
  ],
  // ...
}
```

When a user tries to access a protected route, a login dialog will appear prompting them to sign in
or register. After logging in, they are automatically redirected back to the route they were trying
to access, including its query string.

:::caution{title="redirectToAfterSignIn takes precedence"}

If `authentication.redirectToAfterSignIn` is set, users are sent to that path after every sign-in
instead of the page they were trying to open. Leave it unset to return users to where they were. See
[Redirects after sign-in](./authentication.md#redirects-after-sign-in).

:::

## Object Format

For more complex authorization logic, you can provide a record mapping route patterns to custom
callback functions:

```typescript title="zudoku.config.ts"
{
  // ...
  protectedRoutes: {
    // Only allow authenticated users with admin role
    "/admin/*": ({ auth }) =>
      auth.isAuthenticated && auth.user?.role === "admin",

    // Check if user has enterprise access
    "/api/enterprise/*": ({ auth }) =>
      auth.isAuthenticated && auth.user?.subscription === "enterprise",

    // Allow access to beta features based on user attributes
    "/beta/*": ({ auth }) =>
      auth.isAuthenticated && auth.user?.betaAccess === true,
  },
  // ...
}
```

### Callback Parameters

The callback function receives an object with:

- `auth` - The current authentication state, including `isAuthenticated`, `isPending`, `profile`,
  and more
- `context` - The Zudoku context providing access to configuration and utilities
- `reasonCode` - An object containing the reason code constants `UNAUTHORIZED` and `FORBIDDEN` (see
  [Reason Codes](#reason-codes))

### Return Values

The callback can return a `boolean` or a reason code string:

| Return value              | Behavior                                          |
| ------------------------- | ------------------------------------------------- |
| `true`                    | Allow access to the route                         |
| `false`                   | Treated as `UNAUTHORIZED` - prompts login         |
| `reasonCode.UNAUTHORIZED` | Show a login dialog prompting the user to sign in |
| `reasonCode.FORBIDDEN`    | Show a 403 "Access Denied" page                   |

## Reason Codes

Reason codes allow you to distinguish between users who need to sign in and users who are signed in
but lack permission. This is useful for building role-based or attribute-based access control.

- **`UNAUTHORIZED`** - The user is not authenticated. A login dialog is shown, and navigation to the
  route is blocked until the user signs in.
- **`FORBIDDEN`** - The user is authenticated but does not have permission. A 403 "Access Denied"
  page is displayed instead of the route content.

```typescript title="zudoku.config.ts"
{
  // ...
  protectedRoutes: {
    // Members-only page: unauthenticated users see a login prompt
    "/only-members": ({ auth, reasonCode }) =>
      auth.isAuthenticated ? true : reasonCode.UNAUTHORIZED,

    // VIP page: unauthenticated users see a login prompt,
    // authenticated users without permission see "Access Denied"
    "/vip-lounge": ({ auth, reasonCode }) =>
      !auth.isAuthenticated
        ? reasonCode.UNAUTHORIZED
        : auth.profile?.email?.endsWith("@example.com")
          ? true
          : reasonCode.FORBIDDEN,
  },
  // ...
}
```

## Navigation Blocking

When a user navigates to a route that returns `false` or `UNAUTHORIZED`, navigation is intercepted
before the page changes. The user stays on the current page while a login dialog is displayed. If
the user cancels, they remain on the current page. If they log in successfully, navigation
automatically proceeds to the protected route.

Routes that return `FORBIDDEN` do not block navigation — the user navigates to the route and sees
the "Access Denied" page.

## Path Patterns

The path patterns follow the same syntax as [React Router](https://reactrouter.com):

- `:param` matches a URL segment up to the next `/`, `?`, or `#`
- `*` matches zero or more characters up to the next `/`, `?`, or `#`
- `/*` matches all characters after the pattern

For example:

- `/users/:id` matches `/users/123` or `/users/abc`
- `/docs/*` matches `/docs/getting-started` or `/docs/api/reference`
- `/settings` matches only the exact path `/settings`

## Server-side Protection (SSR mode)

In SSR mode, Zudoku additionally isolates the JavaScript chunks for protected routes into an
auth-gated directory that unauthenticated users cannot fetch. This covers content sources that the
build can statically analyze (MDX docs, file-based OpenAPI, user custom pages with `lazy` imports)
and has caveats for dynamically-generated routes and inline content.

See the [Server-side Content Protection guide](../guides/server-side-content-protection.md) for the
full explanation, auto-detection rules, caveats, and pre-ship checklist.

## Next Steps

- Learn about [authentication providers](./authentication.md#authentication-providers) supported by
  Zudoku
- Configure [user data](./authentication.md#user-data) display
- Read the [Server-side Content Protection guide](../guides/server-side-content-protection.md) if
  you're deploying with an SSR adapter
