jamdesk 1.1.203 → 1.1.205

package/vendored/lib/render-doc-page.tsx

@@ -78,7 +78,7 @@ import {
   parseFrontmatter,
   projectExists,
 } from '@/lib/content-loader';
-import { getBaseUrl, getBaseUrlFromConfig, pathToSlug } from '@/lib/page-isr-helpers';
+import { getBaseUrl, getBaseUrlFromConfig } from '@/lib/page-isr-helpers';
 import { prefixRelativeHref } from '@/lib/link-prefix-helpers';
 import {
   parseOpenApiFrontmatter,
@@ -93,10 +93,10 @@ import {
 } from '@/lib/openapi';
 import { classifyOpenApiLoadError } from '@/lib/openapi/classify-load-error';
 import { findOperation, deriveOperationDescription, collectLocalSpecPaths } from '@/lib/openapi/operation-description';
-import { extractLanguageFromPath, isValidLanguageCode, resolveLocaleFromPath } from '@/lib/language-utils';
+import { extractLanguageFromPath, resolveLocaleFromPath } from '@/lib/language-utils';
 import { parseLocalePath } from '@/lib/locale-fallback';
 import { DocsLocaleProvider } from '@/components/mdx/docs-locale-context';
-import { findFirstNavPage } from '@/lib/find-first-nav-page';
+import { needsSlugRewrite, resolveMarkdownFallbackPath, resolveSlug } from '@/lib/root-page-slug';
 import { candidateSpecPaths } from '@/lib/openapi/lang-spec-path';
 import { squeezeToPageDescription } from '@/lib/openapi/squeeze-page-description';
 import { ApiEndpoint } from '@/components/mdx/ApiEndpoint';
@@ -106,6 +106,7 @@ import { withApiSpecDownload } from '@/lib/api-spec-menu-gate';
 import { SnippetComponents } from '@/components/snippets/ProjectSnippets';
 import { EmailSubscribe } from '@/components/mdx/EmailSubscribe';
 import { resolveAutoNewsletter, mdxHasEmailSubscribe } from '@/lib/email-subscribe-autoplacement';
+import { filterNavigationForViewer } from '@/lib/viewer-navigation';
 
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
 
@@ -231,13 +232,6 @@ function resolveAuth(
   return endpoint ? deriveAuthFromSecurity(endpoint.security) : {};
 }
 
-function findFirstPage(config: DocsConfig, lang?: string): string {
-  const nav = config.navigation;
-  const langBlock = lang ? nav.languages?.find((l) => l.language === lang) : undefined;
-  const result = (langBlock && findFirstNavPage(langBlock)) || findFirstNavPage(nav);
-  return result ? result.replace(/^\//, '') : 'introduction';
-}
-
 /**
  * Every locale this project declared in docs.json — the whitelist the localized
  * component chrome (`resolveLocaleFromPath`) gates on. Empty for a project with
@@ -296,18 +290,6 @@ function fallbackLocales(config: DocsConfig): string[] {
   return languages.filter((l) => l.language !== defaultLang).map((l) => l.language);
 }
 
-function needsSlugRewrite(slug: string[]): boolean {
-  return slug.length === 0 || (slug.length === 1 && isValidLanguageCode(slug[0]));
-}
-
-function resolveSlug(normalizedSlug: string[], config: DocsConfig): string[] {
-  if (normalizedSlug.length === 0) return pathToSlug(findFirstPage(config));
-  if (normalizedSlug.length === 1 && isValidLanguageCode(normalizedSlug[0])) {
-    return pathToSlug(findFirstPage(config, normalizedSlug[0]));
-  }
-  return normalizedSlug;
-}
-
 /**
  * Resolve a page `<meta>`/og description from its OpenAPI operation when the
  * page has no frontmatter `description`. Pure: the spec loader is injected so
@@ -451,17 +433,38 @@ export async function buildDocMetadata(input: RenderInput): Promise<Metadata> {
   // Bare `/` or `/<lang>` roots render the first nav page but keep the alias URL;
   // suppress hreflang on them (passed to buildSeoMetadata — see its isRootAlias
   // doc for why).
-  const isRootAlias = needsSlugRewrite(normalizedSlug);
-  const slug = isRootAlias
+  const isAliasSlug = needsSlugRewrite(normalizedSlug);
+  const slug = isAliasSlug
     ? resolveSlug(normalizedSlug, await configP)
     : normalizedSlug;
-  const pagePath = slug.join('/');
+  const literalPath = slug.join('/');
 
-  const [pageContents, config] = await Promise.all([
-    loader.getContent(pagePath).catch(() => null),
+  const [literalContents, config] = await Promise.all([
+    loader.getContent(literalPath).catch(() => null),
     configP,
   ]);
 
+  // `<prefix>/index` is the site root spelled out — the proxy collapses `/` and
+  // `/index.md` to the page path `index`, so the markdown export has always
+  // answered it, while HTML 404'd because `/docs` yields the empty slug and
+  // `/docs/index` yields `['index']`. That asymmetry let an agent cite a URL
+  // that 404s for a human. Resolve it the way the .md route does — LITERAL
+  // FIRST, fallback second — so a tenant with a real `index.mdx` still reaches
+  // it here, and only a tenant without one falls through to the first nav page.
+  // A miss on any other path stays a 404: resolveMarkdownFallbackPath returns
+  // null for everything except the root sentinel and a bare language code.
+  const rootFallbackPath = literalContents
+    ? null
+    : resolveMarkdownFallbackPath(literalPath, config);
+  const rootFallbackContents = rootFallbackPath
+    ? await loader.getContent(rootFallbackPath).catch(() => null)
+    : null;
+
+  const pageContents = literalContents ?? rootFallbackContents;
+  const pagePath = rootFallbackContents ? rootFallbackPath! : literalPath;
+  // A fallback render IS a root alias: same page, same hreflang/JSON-LD shape.
+  const isRootAlias = isAliasSlug || rootFallbackContents !== null;
+
   // Untranslated locale page → serve the English page's metadata for it (see
   // lib/locale-fallback). This block MUST stay in lockstep with the identical
   // one in renderDocPage: they are two Next entry points over ONE URL, and a
@@ -575,24 +578,46 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
   const highlighterP = getHighlighter();
 
   const normalizedSlug = normalizeSlugForContent(slugInput || [], hostAtDocs);
-  const isRootAlias = needsSlugRewrite(normalizedSlug);
-  const slug = isRootAlias
+  const isAliasSlug = needsSlugRewrite(normalizedSlug);
+  const slug = isAliasSlug
     ? resolveSlug(normalizedSlug, await configP)
     : normalizedSlug;
-  const pagePath = slug.join('/');
-  const currentLang = extractLanguageFromPath(`/${pagePath}`);
-  const [pageContents, config, highlighter] = await Promise.all([
-    loader.getContent(pagePath).catch(() => null),
+  const literalPath = slug.join('/');
+  const [literalContents, loadedConfig, highlighter] = await Promise.all([
+    loader.getContent(literalPath).catch(() => null),
     configP,
     highlighterP,
   ]);
 
+  // `<prefix>/index` is the site root spelled out — the proxy collapses `/` and
+  // `/index.md` to the page path `index`, so the markdown export has always
+  // answered it, while HTML 404'd because `/docs` yields the empty slug and
+  // `/docs/index` yields `['index']`. That asymmetry let an agent cite a URL
+  // that 404s for a human. Resolve it the way the .md route does — LITERAL
+  // FIRST, fallback second — so a tenant with a real `index.mdx` still reaches
+  // it here, and only a tenant without one falls through to the first nav page.
+  // A miss on any other path stays a 404: resolveMarkdownFallbackPath returns
+  // null for everything except the root sentinel and a bare language code.
+  // Mirror of the block in buildDocMetadata — the two entry points must reach
+  // the same verdict on the same URL, or metadata and body disagree.
+  const rootFallbackPath = literalContents
+    ? null
+    : resolveMarkdownFallbackPath(literalPath, loadedConfig);
+  const rootFallbackContents = rootFallbackPath
+    ? await loader.getContent(rootFallbackPath).catch(() => null)
+    : null;
+
+  const pageContents = literalContents ?? rootFallbackContents;
+  const pagePath = rootFallbackContents ? rootFallbackPath! : literalPath;
+  const isRootAlias = isAliasSlug || rootFallbackContents !== null;
+  const currentLang = extractLanguageFromPath(`/${pagePath}`);
+
   // Untranslated locale page → serve the English body with a notice instead of
   // 404ing. Mirror of the block in buildDocMetadata — see the comment there for
   // why both entry points must reach the same verdict on the same URL.
   const localeFallback = pageContents
     ? null
-    : parseLocalePath(pagePath, fallbackLocales(config));
+    : parseLocalePath(pagePath, fallbackLocales(loadedConfig));
   const fileContents = pageContents ?? (localeFallback
     ? await loader.getContent(localeFallback.englishPath).catch(() => null)
     : null);
@@ -609,6 +634,17 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
     });
   }
 
+  // Same viewer filter the root layout applies: this config feeds the
+  // breadcrumb and the prev/next pager, which would otherwise name a
+  // group-restricted neighbour the edge 404s for this viewer.
+  let config = loadedConfig;
+  if (isIsr && projectSlug && requestHeaders && config.auth?.jwt?.enabled) {
+    config = {
+      ...config,
+      navigation: await filterNavigationForViewer(projectSlug, config.navigation, requestHeaders),
+    };
+  }
+
   const parsed = parseFrontmatter(fileContents);
   const data = parsed.data as FrontmatterData;
   const rawContent = parsed.content;
@@ -1091,6 +1127,10 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
 
   const resolvedMdxAuth = resolveAuth(mdxEndpointData, config);
   const resolvedOpenApiAuth = resolveAuth(openApiEndpointData, config);
+  // Drives the playground's post-mount /_jd/api/auth/me fetch that pre-fills
+  // auth/params from the signed-in session — only worth the round-trip when
+  // JWT auth is actually opted into for this project.
+  const jwtAuthEnabled = config.auth?.jwt?.enabled === true;
 
   // Pass the RAW MDX content — preprocessMdx() runs stripSnippetImports(),
   // which would erase the `import X from '/snippets/...'` lines that the
@@ -1144,6 +1184,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
                     serverUrl={fallbackServerUrl}
                     proxyEnabled={proxyEnabled}
                     languages={config.api?.examples?.languages}
+                    jwtAuthEnabled={jwtAuthEnabled}
                   />
                 ) : (
                   <ApiEndpoint
@@ -1166,6 +1207,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
                   proxyEnabled={proxyEnabled}
                   languages={config.api?.examples?.languages}
                   descriptionAlreadyShown={descriptionAlreadyShown}
+                  jwtAuthEnabled={jwtAuthEnabled}
                 />
               )}
 

package/vendored/lib/root-page-slug.ts

@@ -0,0 +1,110 @@
+/**
+ * Root-alias resolution shared by the HTML renderer and the markdown export.
+ *
+ * `/` and `/<lang>` render the first navigation page IN PLACE — no redirect,
+ * the alias URL stays in the address bar. render-doc-page.tsx has done that
+ * for HTML since the alias URLs were introduced. The markdown export never
+ * did: the proxy collapses `/`, `/index.md`, `/docs` and `/docs/index.md` to
+ * the page path `index` (and `/fr` to `fr`), and both markdown routes fetched
+ * that path verbatim, so every tenant whose root page is not literally
+ * `index.mdx` 404'd its own home page to agents (found 2026-09-10 through
+ * afdocs' markdown-url-support probes). Both surfaces now resolve through
+ * this one module so they cannot drift again.
+ *
+ * isValidLanguageCode is `Object.hasOwn`, not `in` (tightened 2026-09-10), so
+ * `constructor` / `toString` / `hasOwnProperty` are ordinary page names on both
+ * surfaces: they fall through needsSlugRewrite to the literal path instead of
+ * resolving to the first nav page. Parity with HTML is the contract here — the
+ * helper is shared, so the two surfaces move together.
+ */
+import type { DocsConfig } from '@/lib/docs-types';
+import { findFirstNavPage } from '@/lib/find-first-nav-page';
+import { isValidLanguageCode } from '@/lib/language-utils';
+import { pathToSlug } from '@/lib/page-isr-helpers';
+
+/**
+ * The page path proxy.ts rewrites the site root to (`/`, `/index.md`, and the
+ * hostAtDocs `/docs` forms). Reference this, never the literal, in the routes.
+ */
+export const ROOT_MARKDOWN_SENTINEL = 'index';
+
+/**
+ * First leaf page of the navigation, without its leading slash. With `lang`,
+ * that language block's first page wins; an undeclared or empty block falls
+ * through to the whole nav. `'introduction'` is the historical default for a
+ * nav with no leaf page at all.
+ */
+export function findFirstPage(config: DocsConfig, lang?: string): string {
+  const nav = config.navigation;
+  const langBlock = lang ? nav.languages?.find((l) => l.language === lang) : undefined;
+  const result = (langBlock && findFirstNavPage(langBlock)) || findFirstNavPage(nav);
+  return result ? result.replace(/^\//, '') : 'introduction';
+}
+
+/**
+ * `/` or a bare `/<lang>` — the two URL shapes that render a page they do not name.
+ *
+ * DELIBERATE, do not "tighten" this to the tenant's declared languages: the test
+ * is against the GLOBAL language list, so all ~34 codes alias the first nav page
+ * on every tenant, including ones that declare no languages at all
+ * (`acme.jamdesk.app/ru` and `/ru.md` both serve the English home page). That is
+ * `findFirstPage`'s documented contract — an undeclared language block falls
+ * through to the whole nav — and HTML has behaved this way since alias URLs were
+ * introduced; the markdown export was brought into line with it on purpose, so
+ * the two surfaces agree.
+ *
+ * Gating on `config.navigation.languages` would 404 a bookmarked `/en` on every
+ * monolingual tenant, and would have to change all three consumers at once
+ * (render-doc-page's two entry points and resolveMarkdownFallbackPath, which
+ * feeds both markdown routes). The cost of leaving it is agent-facing only —
+ * ~34 phantom URLs per tenant that all return the same page — and `.md` carries
+ * `noindex, nofollow`, so there is no search exposure. Revisit only with an
+ * owner decision, not as a cleanup.
+ */
+export function needsSlugRewrite(slug: string[]): boolean {
+  return slug.length === 0 || (slug.length === 1 && isValidLanguageCode(slug[0]));
+}
+
+/**
+ * HTML-side resolution: the alias slug → the first page's slug segments;
+ * any other slug passes through untouched. `normalizedSlug[0]` is the language
+ * for a bare `/<lang>` and `undefined` for the empty root slug — which is
+ * exactly `findFirstPage`'s optional-lang contract, so the two alias shapes
+ * share one line and only `needsSlugRewrite` defines what an alias IS.
+ */
+export function resolveSlug(normalizedSlug: string[], config: DocsConfig): string[] {
+  if (!needsSlugRewrite(normalizedSlug)) return normalizedSlug;
+  return pathToSlug(findFirstPage(config, normalizedSlug[0]));
+}
+
+/**
+ * Markdown-side resolution for a page path that was NOT found in the content
+ * store. Only the two root aliases get a fallback — the `index` sentinel and a
+ * bare language code — and only when the first nav page is a different path.
+ * So a missing real page still 404s, and a project whose first page IS `index`
+ * never fetches the same key twice. Callers try the literal path first: a
+ * project with a real `index.mdx` keeps serving it, which is the one deliberate
+ * difference from the HTML root (which never consults `index.mdx`).
+ *
+ * @returns the page path to fetch instead, or null when there is no fallback
+ */
+export function resolveMarkdownFallbackPath(
+  requestedPath: string,
+  config: DocsConfig | null | undefined,
+): string | null {
+  if (!config?.navigation) return null;
+
+  // Re-express the page path as the slug the HTML path would have seen, so the
+  // alias test and the resolution are the SAME code on both surfaces: `index`
+  // is the proxy's stand-in for the empty root slug, and a bare language code
+  // is already a single segment. Anything else — including a nested page and
+  // the empty string — fails needsSlugRewrite, so a real miss stays a 404.
+  const aliasSlug = requestedPath === ROOT_MARKDOWN_SENTINEL ? [] : [requestedPath];
+  if (!needsSlugRewrite(aliasSlug)) return null;
+
+  // resolveSlug brings pathToSlug's normalisation with it: a nav entry authored
+  // as "/introduction" or "introduction/" must become the clean R2 key, and the
+  // equality guard must compare clean to clean.
+  const normalized = resolveSlug(aliasSlug, config).join('/');
+  return normalized === requestedPath ? null : normalized;
+}

package/vendored/lib/same-origin.ts

@@ -0,0 +1,38 @@
+/**
+ * Same-origin guard for cookie-minting POST routes (JWT callback, password
+ * unlock). Both routes set a session cookie from a POST body, and a browser
+ * will happily send that POST cross-site — a page on evil.example.com can
+ * submit a text/plain form or fetch() to <docs-host>/api/jd/auth/callback,
+ * and the response's Set-Cookie lands in the victim's jar (login-CSRF). With
+ * the JWT route that means an attacker-chosen session, including groups and
+ * API-playground inputs the playground then auto-fills.
+ *
+ * Decision, in order:
+ *   1. `Sec-Fetch-Site` when present is authoritative (browsers set it and
+ *      pages cannot forge it): `same-origin` and `none` (user-typed
+ *      navigation) pass; `cross-site` and `same-site` fail — a sibling
+ *      *.jamdesk.app subdomain is another tenant, so same-site is NOT ok.
+ *   2. Otherwise `Origin` when present must match the request host —
+ *      the customer-forwarded public host first (x-jamdesk-forwarded-host),
+ *      then Host — case-insensitively. `Origin: null` (sandboxed/opaque
+ *      contexts) fails.
+ *   3. Neither header → allow. Non-browser clients (curl, the smoke harness)
+ *      send neither, and every browser that can mount the attack sends at
+ *      least one of them on a cross-site POST.
+ */
+export function isSameOriginRequest(req: Request): boolean {
+  const fetchSite = req.headers.get('sec-fetch-site');
+  if (fetchSite) {
+    return fetchSite === 'same-origin' || fetchSite === 'none';
+  }
+  const origin = req.headers.get('origin');
+  if (!origin) return true;
+  let originHost: string;
+  try {
+    originHost = new URL(origin).host;
+  } catch {
+    return false; // includes the literal "null"
+  }
+  const requestHost = req.headers.get('x-jamdesk-forwarded-host') || req.headers.get('host') || '';
+  return originHost.toLowerCase() === requestHost.toLowerCase();
+}

package/vendored/lib/sanitize-from.ts

@@ -29,8 +29,38 @@ export function sanitizeFrom(raw: string | null | undefined): string {
   // form to catch percent-encoded slashes like /%2F%2Fevil.com → //evil.com.
   const normalized = parsed.pathname + parsed.search + parsed.hash;
   if (parsed.pathname.startsWith('//')) return '/';
-  const decodedPathname = decodeURIComponent(parsed.pathname);
+  // The URL parser passes malformed percent-sequences through verbatim
+  // ('/%', '/a%2'), where decodeURIComponent throws — if we can't decode we
+  // can't rule out an encoded //, so reject rather than 500.
+  let decodedPathname: string;
+  try {
+    decodedPathname = decodeURIComponent(parsed.pathname);
+  } catch {
+    return '/';
+  }
   if (decodedPathname.startsWith('//')) return '/';
 
   return normalized;
 }
+
+/**
+ * Redirect sanitizer for the JWT auth callback. sanitizeFrom does the heavy
+ * lifting (same-site path only; rejects CRLF, backslashes, protocol-relative
+ * and percent-encoded // forms); this only adds the auth self-loop guards:
+ * the callback page itself, and the auth API routes — /api/jd/auth/logout is
+ * a GET that clears the cookie, so a crafted `redirect` would log the freshly
+ * minted session straight back out. Both the legacy paths and the /_jd
+ * aliases are served, so both prefixes are refused.
+ */
+const CALLBACK_REDIRECT_DENY_PREFIXES = ['/jd/auth/', '/_jd/auth/', '/api/jd/auth/', '/_jd/api/auth/'];
+
+export function sanitizeCallbackRedirect(raw: unknown): string {
+  const path = sanitizeFrom(typeof raw === 'string' ? raw : null);
+  // Match on the DECODED path: sanitizeFrom keeps percent-encoding, and the
+  // router decodes before matching, so `/%61pi/jd/auth/logout` would reach
+  // logout while slipping past a literal prefix check.
+  let decoded = path;
+  try { decoded = decodeURIComponent(path); } catch { return '/'; }
+  if (CALLBACK_REDIRECT_DENY_PREFIXES.some((prefix) => decoded.startsWith(prefix))) return '/';
+  return path;
+}

package/vendored/lib/session-hint.ts

@@ -0,0 +1,11 @@
+/**
+ * The `jd_authed=1` hint cookie is set by the JWT callback and cleared by
+ * logout. It is client-readable, carries nothing, and has no security value —
+ * the signed HttpOnly session cookie behind /_jd/api/auth/me is what's
+ * trusted. Its only job is to let client components skip the /me round-trip
+ * on anonymous views (every SEO landing and shared link would otherwise pay
+ * it). Shared by the header logout affordance and the API playground pre-fill.
+ */
+export function hasJwtSessionHint(cookieString: string): boolean {
+  return cookieString.split('; ').includes('jd_authed=1');
+}

package/vendored/lib/snippet-compiler-isr.ts

@@ -66,7 +66,7 @@ export async function compileSnippetIsr(
     filename: snippetPath,
   });
 
-  if (!transpiled.code) {
+  if (!transpiled?.code) {
     throw new Error(`Failed to compile snippet: ${snippetPath}`);
   }
 

package/vendored/lib/snippet-loader-isr.ts

@@ -194,7 +194,7 @@ export function transpileJsx(source: string): string {
     filename: 'snippet.tsx',
   });
 
-  if (!result.code) {
+  if (!result?.code) {
     throw new Error('Babel transpilation failed');
   }
 

package/vendored/lib/validate-config.ts

@@ -21,6 +21,7 @@ import JSON5 from 'json5';
 import fs from 'fs';
 import path from 'path';
 import { BUILD_SERVICE_DIR } from './paths.js';
+import { validateJwtAuth } from './jwt-auth-config.js';
 
 // Types
 export interface DocsConfig {
@@ -592,6 +593,19 @@ export async function validateConfig(
     };
   }
 
+  // validate-config.ts's local DocsConfig (theme optional, pre-schema-validation)
+  // is structurally close to but not assignable to docs-types.ts's DocsConfig
+  // (theme required) — validateJwtAuth only reads `config.auth`, which both
+  // shapes carry via their `[key: string]: unknown` index signatures.
+  const jwtErrors = validateJwtAuth(config as unknown as Parameters<typeof validateJwtAuth>[0]);
+  if (jwtErrors.length > 0) {
+    return {
+      valid: false,
+      error: `Invalid docs.json: ${jwtErrors[0]}`,
+      errorType: 'config_error',
+    };
+  }
+
   // Try schema validation if available (non-blocking if schema not available)
   try {
     const schema = await getSchema();

package/vendored/lib/viewer-navigation.ts

@@ -0,0 +1,45 @@
+import type { DocsConfig } from './docs-types';
+import { resolveAuth } from './auth-resolver';
+import { verifyAuthCookie } from '../shared/auth-cookie';
+import { filterNavigationForGroups } from './nav-group-filter';
+
+/**
+ * Drop group-restricted pages the viewer can't access from the navigation
+ * before it reaches the client. Server-only (reads Redis + the session
+ * cookie). Two consumers must agree: the root layout (sidebar/tabs/header
+ * resolve navigation from its config in the browser) and the page render
+ * (breadcrumb + prev/next pager). Without this every public page's RSC
+ * payload lists the titles and hrefs of pages the edge answers with a 404
+ * to out-of-group users — defeating the point of the 404.
+ *
+ * Group membership comes from the SERVER-VERIFIED v2 session cookie (same
+ * check as /_jd/api/auth/me), never the client-readable jd_authed hint.
+ * Cookie verification fails closed to "no groups" (over-hides). A resolver
+ * failure is different: the group map itself is unavailable, so the
+ * navigation is returned unfiltered rather than taking the page down — the
+ * edge gate 503s the request on the same outage, so this only renders when
+ * the edge and Node runtimes' 15s caches disagree.
+ */
+export async function filterNavigationForViewer(
+  slug: string,
+  navigation: DocsConfig['navigation'],
+  headersList: Headers,
+): Promise<DocsConfig['navigation']> {
+  let auth: Awaited<ReturnType<typeof resolveAuth>> = null;
+  try { auth = await resolveAuth(slug); } catch { /* group map unavailable: unfiltered */ }
+  if (!auth || auth.authType !== 'jwt' || !auth.groupsPaths) return navigation;
+  if (Object.keys(auth.groupsPaths).length === 0) return navigation;
+
+  let userGroups: string[] = [];
+  const secret = process.env.EDGE_AUTH_SECRET;
+  const cookieHeader = headersList.get('cookie') || '';
+  const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)jd_auth_${slug}=([^;]+)`));
+  if (secret && match) {
+    const host = headersList.get('x-jamdesk-forwarded-host') || headersList.get('host') || '';
+    try {
+      const v = await verifyAuthCookie(match[1], { slug, host, version: auth.version }, secret);
+      if (v.valid && v.formatVersion === 'v2') userGroups = v.extras?.g ?? [];
+    } catch { /* fail closed: no groups */ }
+  }
+  return filterNavigationForGroups(navigation, auth.groupsPaths, userGroups);
+}

package/vendored/lib/visibility.ts

@@ -1,5 +1,6 @@
 import type { DocsConfig, NavigationConfig } from './docs-types.js';
 import { RECURSE_KEYS } from './enhance-navigation.js';
+import { MAX_GROUP_NAME_LEN } from './public-paths-resolver.js';
 
 /**
  * Result of walking the nav tree for hidden-state classification.
@@ -120,12 +121,24 @@ export interface VisibilityInputs {
   navPaths: Set<string>;
   hiddenNavPaths: Set<string>;
   searchableNavPaths: Set<string>;
+  /**
+   * Slug (no leading slash, extension stripped — same convention as `path` and
+   * `navPaths`/`hiddenNavPaths`) → required groups, from
+   * lib/public-paths-resolver.ts's `collectGroupsPaths`. This map is what
+   * carries locale inheritance: a translated page (e.g. `fr/admin`) whose own
+   * frontmatter lacks `groups` still shows up here because collectGroupsPaths
+   * propagates the base page's restriction onto it. Optional/omitted (or
+   * empty, as in non-jwt auth modes) preserves the own-frontmatter-only
+   * fallback in `isGroupRestricted` below.
+   */
+  groupsPaths?: Record<string, string[]>;
 }
 
 export interface PageFrontmatterForVisibility {
   hidden?: boolean;
   noindex?: boolean;
   seo?: { noindex?: boolean };
+  groups?: unknown;
 }
 
 export interface PageVisibility {
@@ -135,17 +148,60 @@ export interface PageVisibility {
     | 'orphan'
     | 'frontmatter-hidden'
     | 'frontmatter-noindex'
+    | 'frontmatter-groups'
     | 'nav-hidden'
     | 'override-indexing-all'
     | 'override-indexHiddenPages';
 }
 
+/**
+ * True when frontmatter carries a real group restriction: an array with at
+ * least one VALID entry. Validity mirrors collectGroupsPaths' per-entry
+ * filter exactly (typeof === 'string', non-empty, <= MAX_GROUP_NAME_LEN) —
+ * so `groups: [123]` or `groups: ['x'.repeat(65)]` is judged unrestricted
+ * here too. Without this parity, a page whose only entries are junk would be
+ * fail-closed (hidden from search/sitemap/RAG) here while the runtime edge
+ * gate (which uses the same filter) fail-opens it as public — a page that's
+ * reachable but invisible, not the access-control divergence this guards
+ * against being read the other way around.
+ */
+export function hasGroupRestriction(frontmatter: unknown): boolean {
+  const groups = (frontmatter as { groups?: unknown } | undefined)?.groups;
+  if (!Array.isArray(groups)) return false;
+  return groups.some(
+    (g): g is string => typeof g === 'string' && g.length > 0 && g.length <= MAX_GROUP_NAME_LEN,
+  );
+}
+
+/**
+ * True when a page is group-restricted, considering BOTH its own frontmatter
+ * and locale inheritance. `groupsPaths` (from collectGroupsPaths) carries
+ * restrictions forward onto translated variants that lack their own `groups`
+ * field — a translated page's frontmatter routinely drops fields the base
+ * page had, so checking `frontmatter` alone would silently reopen every
+ * localized variant of a restricted page. `path` must already be normalized
+ * to the same leading-slash-free convention as `groupsPaths`' keys and the
+ * rest of VisibilityInputs (navPaths etc.) — callers own that normalization.
+ */
+export function isGroupRestricted(
+  path: string,
+  frontmatter: unknown,
+  groupsPaths?: Record<string, string[]>,
+): boolean {
+  if (hasGroupRestriction(frontmatter)) return true;
+  const inherited = groupsPaths?.[path];
+  return Array.isArray(inherited) && inherited.length > 0;
+}
+
 /**
  * The single function that decides whether a page is in the sitemap / llms.txt /
  * llms-full.txt / search index. Same logic for all four artifacts.
  *
  *  Excluded when ANY of:
  *    - frontmatter.noindex or frontmatter.seo.noindex
+ *    - the page is group-restricted per isGroupRestricted (own frontmatter.groups
+ *      OR inherited via inputs.groupsPaths — see that function) (access control —
+ *      NEVER overrideable, not even by indexHiddenPages or indexing:'all')
  *    - frontmatter.hidden (UNLESS indexHiddenPages or indexing:'all')
  *    - path not in navigation (orphan) AND indexing !== 'all'
  *    - path in hiddenNavPaths AND NOT in searchableNavPaths (UNLESS indexHiddenPages or indexing:'all')
@@ -168,6 +224,15 @@ export function computePageVisibility(
     return { inArtifacts: false, reason: 'frontmatter-noindex' };
   }
 
+  // Group-restricted pages are access-controlled content: never list them in
+  // sitemap/llms/search artifacts, regardless of seo indexing overrides —
+  // those overrides express SEO preference, not permission to leak titles.
+  // isGroupRestricted also catches locale-inherited restriction (a translated
+  // page whose own frontmatter dropped `groups`) via inputs.groupsPaths.
+  if (isGroupRestricted(path, frontmatter, inputs.groupsPaths)) {
+    return { inArtifacts: false, reason: 'frontmatter-groups' };
+  }
+
   // frontmatter.hidden wins over everything except noindex (checked above).
   // Mintlify spec rule #7: page-level hidden always wins over parent searchable.
   if (frontmatter.hidden === true && !override) {

package/vendored/schema/docs-schema.json

@@ -1694,6 +1694,31 @@
                                     "uniqueItems": true
                                 }
                             }
+                        },
+                        "jwt": {
+                            "type": "object",
+                            "description": "JWT authentication. Generate the signing key in the Jamdesk dashboard; this block controls opt-in, your login URL, and public path exceptions.",
+                            "additionalProperties": false,
+                            "properties": {
+                                "enabled": {
+                                    "type": "boolean",
+                                    "description": "Require JWT authentication for the whole site."
+                                },
+                                "loginUrl": {
+                                    "type": "string",
+                                    "format": "uri",
+                                    "description": "Absolute https:// URL of your login flow. Visitors are redirected here with ?redirect=<path>."
+                                },
+                                "public": {
+                                    "type": "array",
+                                    "maxItems": 100,
+                                    "items": {
+                                        "type": "string",
+                                        "pattern": "^/[A-Za-z0-9._*/-]+$"
+                                    },
+                                    "description": "Paths or globs that bypass authentication. Supports '*' and '**'."
+                                }
+                            }
                         }
                     }
                 },