jamdesk 1.1.204 → 1.1.205

package/vendored/app/api/jd/unlock/route.ts

@@ -19,11 +19,12 @@ export const dynamic = 'force-dynamic';
 import { scrypt, randomBytes, timingSafeEqual } from 'crypto';
 import { promisify } from 'util';
 import { redis } from '@/lib/redis';
-import { getProjectAuthSecret } from '@/lib/cached-redis';
+import { getProjectAuthSecret, getProjectAuthPublic } from '@/lib/cached-redis';
 import { sanitizeFrom } from '@/lib/sanitize-from';
 import { VALID_SLUG_RE } from '@/lib/middleware-helpers';
 import { signAuthCookie } from '@/shared/auth-cookie';
 import { secretsEqual } from '@/lib/crypto-helpers';
+import { isSameOriginRequest } from '@/lib/same-origin';
 
 const scryptAsync = promisify(scrypt) as (
   password: string,
@@ -230,6 +231,13 @@ async function fetchStoredSecret(slug: string): Promise<StoredSecret | null> {
 }
 
 export async function POST(req: Request): Promise<Response> {
+  // Login-CSRF guard: a cross-site form POST would store a session in the
+  // victim's jar. Checked first — before scrypt, before rate limiting — so a
+  // cross-site attacker cannot even use the endpoint as a scrypt oracle.
+  if (!isSameOriginRequest(req)) {
+    return new Response('Forbidden: cross-site request', { status: 403 });
+  }
+
   // Fail-closed: if the signing secret is missing, we cannot issue valid
   // cookies. Return 503 rather than silently issuing unsigned tokens.
   const secret = process.env.EDGE_AUTH_SECRET;
@@ -293,8 +301,14 @@ export async function POST(req: Request): Promise<Response> {
   }
 
   let stored: StoredSecret | null;
+  let authType: 'password' | 'jwt' | undefined;
   try {
-    stored = await fetchStoredSecret(slug);
+    const [storedResult, pubResult] = await Promise.all([
+      fetchStoredSecret(slug),
+      getProjectAuthPublic(slug),
+    ]);
+    stored = storedResult;
+    authType = pubResult?.authType;
   } catch (err) {
     console.error('[unlock] Redis fetch failed — failing closed', {
       slug,
@@ -305,6 +319,16 @@ export async function POST(req: Request): Promise<Response> {
       headers: { 'Retry-After': '30' },
     });
   }
+
+  // JWT-mode projects don't use this route. During a password→jwt migration
+  // coexistence window, a lingering password hash would otherwise let the
+  // unlock form verify and mint a v1 cookie the jwt gate rejects — not a
+  // bypass (the jwt gate never accepts a v1 cookie), but a confusing dead
+  // end for the user. Fail fast instead.
+  if (authType === 'jwt') {
+    return new Response('not-enabled', { status: 404 });
+  }
+
   const hashToVerify = stored?.hash ?? DUMMY_HASH;
 
   // Always run scrypt — even with DUMMY_HASH when no password is set — to

package/vendored/app/layout.tsx

@@ -23,6 +23,7 @@ import type { DocsConfig } from '@/lib/docs-types';
 import { buildSiteTitle, getFaviconIcons, FALLBACK_METADATA } from '@/lib/seo';
 import { withR2OpsContext, emitR2OpsSummary } from '@/lib/r2-content';
 import { DocsChrome, getLocalFileContent, loadCustomAssets } from '@/lib/layout-helpers';
+import { filterNavigationForViewer } from '@/lib/viewer-navigation';
 
 async function generateMetadataImpl(): Promise<Metadata> {
   // The placeholder shell would otherwise render with the paused
@@ -150,6 +151,12 @@ async function rootLayoutImpl({
       try {
         config = await getIsrDocsConfig(projectSlug);
         config = { ...config, hostAtDocs, docsPrefix };
+        if (config.auth?.jwt?.enabled) {
+          config = {
+            ...config,
+            navigation: await filterNavigationForViewer(projectSlug, config.navigation, headersList),
+          };
+        }
       } catch {
         config = {
           name: 'Documentation',

package/vendored/components/mdx/OpenApiEndpoint.tsx

@@ -68,6 +68,9 @@ interface OpenApiEndpointProps {
    *  are the same text — an author's DIFFERENT frontmatter description must
    *  not suppress the operation's own. */
   descriptionAlreadyShown?: boolean;
+  /** When true, PlaygroundModal fetches the signed-in JWT session's
+   *  apiPlaygroundInputs on open and pre-fills matching values. */
+  jwtAuthEnabled?: boolean;
 }
 
 /**
@@ -830,6 +833,7 @@ export function OpenApiEndpoint({
   languages,
   playgroundOnly,
   descriptionAlreadyShown,
+  jwtAuthEnabled,
 }: OpenApiEndpointProps) {
   const {
     method,

package/vendored/components/navigation/Header.tsx

@@ -13,6 +13,7 @@ import { ThemeToggle } from '@/components/theme/ThemeToggle';
 import { LazySearchModal as SearchModal } from '@/components/search/LazySearchModal';
 import { DefaultLogo } from './DefaultLogo';
 import { LanguageSelector } from './LanguageSelector';
+import LogoutButton from './LogoutButton';
 import { resolveNavigation } from '@/lib/navigation-resolver';
 import { getIconClass } from '@/lib/icon-utils';
 import { useLinkPrefix } from '@/lib/link-prefix-context';
@@ -550,6 +551,10 @@ export function Header({ config, layout = 'header-logo', tabsPosition: tabsPosit
               </>
             )}
 
+            {/* Log-out affordance - only mounted for JWT-authenticated docs sites;
+                renders nothing until the client confirms an active session. */}
+            {config.auth?.jwt?.enabled === true && <LogoutButton />}
+
             {/* Theme toggle - hidden on mobile since it's in the sidebar menu.
                 Also hidden when appearance.strict pins users to the configured mode. */}
             {!config.appearance?.strict && (

package/vendored/components/navigation/LogoutButton.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { hasJwtSessionHint } from '../../lib/session-hint';
+
+/**
+ * Only mounted when docs.json has auth.jwt.enabled. The jd_authed hint
+ * cookie (client-readable, set by the callback, cleared by logout) gates the
+ * /me fetch: the Header persists across next/link soft-navs, so this mounts
+ * once per hard load — without the hint, every fresh anonymous entry (SEO
+ * landing, shared link) would pay a /me round-trip. Login and logout both end
+ * in hard loads, so the state re-derives whenever it can change. The hint is
+ * advisory only — the signed session cookie behind /me is what's trusted.
+ * cursor-pointer per UI rule.
+ */
+export default function LogoutButton() {
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    if (!hasJwtSessionHint(document.cookie)) return;
+    let cancelled = false;
+    fetch('/_jd/api/auth/me', { credentials: 'same-origin' })
+      .then((r) => r.json())
+      .then((d: { authenticated?: boolean; authType?: string }) => {
+        if (!cancelled && d.authenticated && d.authType === 'jwt') setVisible(true);
+      })
+      .catch(() => { /* header must render regardless */ });
+    return () => { cancelled = true; };
+  }, []);
+
+  if (!visible) return null;
+  return (
+    <a
+      href="/_jd/auth/logout"
+      className="cursor-pointer"
+      style={{ color: 'var(--color-text-secondary)', fontSize: '0.875rem', whiteSpace: 'nowrap' }}
+    >
+      Log out
+    </a>
+  );
+}

package/vendored/lib/auth-resolver.ts

@@ -1,13 +1,17 @@
 import { redis } from './redis';
-import { getProjectAuthSecret, getProjectAuthPublic } from './cached-redis';
-import { matchPublicPath } from './glob-match';
+import { getProjectAuthSecret, getProjectAuthPublic, getProjectJwtSecret } from './cached-redis';
+import { matchPublicPath, resolveRequiredGroups } from './glob-match';
 
-export { matchPublicPath };
+export { matchPublicPath, resolveRequiredGroups };
 
 export interface ResolvedAuth {
-  hash: string;
+  authType: 'password' | 'jwt';
+  hash?: string;
+  publicKeyPem?: string;
   version: number;
   publicPaths: string[];
+  loginUrl?: string;
+  groupsPaths?: Record<string, string[]>;
 }
 
 interface AuthSecret {
@@ -15,30 +19,50 @@ interface AuthSecret {
   version: number;
 }
 
+interface JwtSecret {
+  publicKeyPem: string;
+  version: number;
+}
+
 interface AuthPublic {
   enabled?: boolean;
   publicPaths?: string[];
+  authType?: 'password' | 'jwt';
+  loginUrl?: string;
+  groupsPaths?: Record<string, string[]>;
 }
 
 /**
- * Resolve active password protection for a project.
+ * Resolve active auth protection (password OR jwt) for a project.
+ *
+ * Truth table — the config plane's declared `authType` alone picks the
+ * ACTIVE mode; the matching secret key must back it or the gate is off:
+ *   projectAuthPublic missing OR enabled!==true                       → no gate (return null)
+ *   authType==='jwt'      AND projectJwtSecret has a publicKeyPem      → jwt gate
+ *   authType==='jwt'      AND projectJwtSecret missing/malformed       → no gate (return null)
+ *   authType!=='jwt' (password, incl. absent) AND projectAuthSecret has a hash → password gate
+ *   authType!=='jwt' AND projectAuthSecret missing/malformed           → no gate (return null)
  *
- * Truth table (both sides must agree for gating to be active):
- *   projectAuthPublic.enabled=true AND projectAuthSecret has a hash → gate
- *   projectAuthPublic missing OR enabled!==true                     → no gate (return null)
- *   projectAuthSecret missing                                       → no gate (return null)
+ * Coexistence is by design: BOTH secret keys may exist simultaneously
+ * during a password→JWT migration (the build writes the new key before
+ * flipping authType, and the old key isn't deleted). Only the
+ * build-written `authType` decides which secret is consulted — a
+ * password hash never satisfies jwt mode and vice versa, so there is no
+ * window where a stale secret of the wrong kind is honored.
  *
- * Both project-level keys fail-CLOSED: if either read throws, this throws
- * `AuthResolutionError` so middleware returns 503 instead of serving gated
- * content without a check. A partial Upstash outage taking down one key
- * while the other is reachable would otherwise create a fail-open window.
+ * All three project-level keys fail-CLOSED: if any read throws, this
+ * throws `AuthResolutionError` so middleware returns 503 instead of
+ * serving gated content without a check. A partial Upstash outage taking
+ * down one key while the others are reachable would otherwise create a
+ * fail-open window.
  *
- * We intentionally do NOT read `domainAuthSecret` here even though it is
- * mirrored on every password write. The dashboard fan-out is best-effort,
- * so a failed mirror write can leave the domain key pointing at a stale
- * version. Reading the mirror would then accept old session cookies on
- * that host. Always reading the project-level key keeps a single source
- * of truth and costs one fewer Redis GET per request on custom domains.
+ * We intentionally do NOT read `domainAuthSecret`/`domainJwtSecret` here
+ * even though they are mirrored on every write. The dashboard fan-out is
+ * best-effort, so a failed mirror write can leave the domain key pointing
+ * at a stale version. Reading the mirror would then accept old session
+ * cookies on that host. Always reading the project-level key keeps a
+ * single source of truth and costs fewer Redis GETs per request on
+ * custom domains.
  *
  * When `redis` is null (local dev without Upstash configured), returns
  * null immediately so the CLI dev server doesn't try to gate anything.
@@ -50,35 +74,33 @@ export class AuthResolutionError extends Error {
   }
 }
 
-export async function resolveAuth(
-  projectSlug: string,
-): Promise<ResolvedAuth | null> {
-  if (!redis) return null;
-
-  let secret: AuthSecret | null;
-  let pub: AuthPublic | null;
-
+// Every auth read shares one failure contract: any throw becomes an
+// AuthResolutionError so callers fail CLOSED rather than treating an
+// unreachable Redis as "not gated".
+async function readOrFail<T>(read: () => Promise<unknown>): Promise<T | null> {
   try {
-    const [secretResult, publicResult] = await Promise.all([
-      getProjectAuthSecret(projectSlug),
-      getProjectAuthPublic(projectSlug),
-    ]);
-    secret = secretResult as AuthSecret | null;
-    pub = publicResult as AuthPublic | null;
+    return (await read()) as T | null;
   } catch (e) {
     throw new AuthResolutionError(
       'Failed to read project auth keys via cached-redis',
       e,
     );
   }
+}
 
-  if (
-    !secret ||
-    typeof secret.hash !== 'string' ||
-    typeof secret.version !== 'number'
-  ) {
-    return null;
-  }
+export async function resolveAuth(
+  projectSlug: string,
+): Promise<ResolvedAuth | null> {
+  if (!redis) return null;
+
+  // Public record FIRST: it decides whether any secret is needed at all, and
+  // which one. A non-gated tenant therefore costs one GET per cache miss
+  // (not three), and each mode reads only its own secret. The extra RTT on a
+  // gated tenant is paid once per 15s cache window, not per request.
+  // Fail-closed is unchanged: any throw becomes AuthResolutionError.
+  const pub = await readOrFail<AuthPublic>(
+    () => getProjectAuthPublic(projectSlug),
+  );
 
   if (!pub || pub.enabled !== true) {
     return null;
@@ -92,11 +114,54 @@ export async function resolveAuth(
   const publicPaths: string[] = Array.isArray(pub.publicPaths)
     ? (pub.publicPaths as string[])
     : [];
+  const authType: 'password' | 'jwt' = pub.authType === 'jwt' ? 'jwt' : 'password';
+
+  if (authType === 'jwt') {
+    const jwtSecret = await readOrFail<JwtSecret>(
+      () => getProjectJwtSecret(projectSlug),
+    );
+    if (
+      !jwtSecret ||
+      typeof jwtSecret.publicKeyPem !== 'string' ||
+      jwtSecret.publicKeyPem.length === 0 ||
+      typeof jwtSecret.version !== 'number'
+    ) {
+      // authType says jwt but the jwt-own secret isn't there (or is
+      // malformed) — gate off. A lingering password hash from a prior
+      // mode must NEVER satisfy jwt mode; that would be a half-on gate.
+      return null;
+    }
+    return {
+      authType,
+      publicKeyPem: jwtSecret.publicKeyPem,
+      version: jwtSecret.version,
+      publicPaths,
+      loginUrl: typeof pub.loginUrl === 'string' ? pub.loginUrl : undefined,
+      groupsPaths:
+        pub.groupsPaths && typeof pub.groupsPaths === 'object'
+          ? pub.groupsPaths
+          : undefined,
+    };
+  }
+
+  const secret = await readOrFail<AuthSecret>(
+    () => getProjectAuthSecret(projectSlug),
+  );
+  if (
+    !secret ||
+    typeof secret.hash !== 'string' ||
+    typeof secret.version !== 'number'
+  ) {
+    return null;
+  }
 
   return {
+    authType,
     hash: secret.hash,
     version: secret.version,
     publicPaths,
+    loginUrl: undefined,
+    groupsPaths: undefined,
   };
 }
 
@@ -117,21 +182,31 @@ export async function resolveAuth(
  * fetch mechanism. Therefore: fail OPEN (return false) on Redis error so
  * brownouts don't nullify the CDN-cache latency win.
  *
- * Reads go through cached-redis (getProjectAuthSecret/getProjectAuthPublic) —
- * the same wrappers resolveAuth uses — so the two share per-instance cache
- * entries for these keys instead of each holding its own copy. cached-redis
- * does NOT cache fetch errors, so the fail-open path below still retries on
- * the next call rather than pinning `false`.
+ * Reads go through cached-redis (getProjectAuthSecret/getProjectAuthPublic/
+ * getProjectJwtSecret) — the same wrappers resolveAuth uses — so the two
+ * share per-instance cache entries for these keys instead of each holding
+ * its own copy. cached-redis does NOT cache fetch errors, so the fail-open
+ * path below still retries on the next call rather than pinning `false`.
+ *
+ * Mirrors resolveAuth's mode binding exactly: a jwt tenant is gated only by
+ * its jwt key, a password tenant only by its hash. A lingering hash from a
+ * previous mode never counts (resolveAuth ignores it too), so the storage
+ * scheme and the edge gate can never disagree about whether a site is open.
  */
 export async function isProjectGated(slug: string): Promise<boolean> {
   if (!redis) return false;
 
   try {
-    const [secret, pub] = await Promise.all([
-      getProjectAuthSecret(slug),
-      getProjectAuthPublic(slug),
-    ]);
-    return !!secret && typeof secret.hash === 'string' && pub?.enabled === true;
+    // Same public-first ordering as resolveAuth (shared cache entries): a
+    // disabled tenant is one GET, and only the mode's own secret is read.
+    const pub = await getProjectAuthPublic(slug);
+    if (pub?.enabled !== true) return false;
+    if (pub.authType === 'jwt') {
+      const jwtSecret = await getProjectJwtSecret(slug);
+      return typeof jwtSecret?.publicKeyPem === 'string';
+    }
+    const secret = await getProjectAuthSecret(slug);
+    return typeof secret?.hash === 'string';
   } catch {
     // Fail OPEN: this is a read-mechanism choice, not access control.
     // Gating already happened upstream in proxy.ts. Failing closed here

package/vendored/lib/cached-redis.ts

@@ -79,7 +79,15 @@ const projectMetaCache = new TtlCache<ProjectMeta>({ ttlMs: POSITIVE_TTL_MS, neg
 // emergency rotation requires the JD_CACHE_DISABLED kill switch + redeploy.
 // See docs/plans/2026-05-21-redis-in-function-memo-cache.md auto-memory.
 const projectAuthSecretCache = new TtlCache<{ hash: string; version: number }>({ ttlMs: AUTH_TTL_MS, negativeTtlMs: NEGATIVE_TTL_MS });
-const projectAuthPublicCache = new TtlCache<{ enabled: boolean; publicPaths: string[] }>({ ttlMs: AUTH_TTL_MS, negativeTtlMs: NEGATIVE_TTL_MS });
+
+export interface ProjectAuthPublic {
+  enabled: boolean;
+  publicPaths: string[];
+  authType?: 'password' | 'jwt';
+  loginUrl?: string;
+  groupsPaths?: Record<string, string[]>;
+}
+const projectAuthPublicCache = new TtlCache<ProjectAuthPublic>({ ttlMs: AUTH_TTL_MS, negativeTtlMs: NEGATIVE_TTL_MS });
 
 const inFlight = new Map<string, Promise<unknown>>();
 
@@ -107,6 +115,7 @@ export function _resetForTest(): void {
   projectMetaCache.clear();
   projectAuthSecretCache.clear();
   projectAuthPublicCache.clear();
+  projectJwtSecretCache.clear();
   inFlight.clear();
   _hits = 0; _misses = 0; _readsSinceLog = 0; _totalReadMs = 0;
   _recent.length = 0; _recentIdx = 0; _recentSum = 0;
@@ -362,8 +371,24 @@ export async function getProjectAuthSecret(slug: string): Promise<{ hash: string
   );
 }
 
-export async function getProjectAuthPublic(slug: string): Promise<{ enabled: boolean; publicPaths: string[] } | null> {
+export async function getProjectAuthPublic(slug: string): Promise<ProjectAuthPublic | null> {
   return readThrough(projectAuthPublicCache, `projectAuthPublic:${slug}`, () =>
-    redis!.get<{ enabled: boolean; publicPaths: string[] }>(`projectAuthPublic:${slug}`),
+    redis!.get<ProjectAuthPublic>(`projectAuthPublic:${slug}`),
+  );
+}
+
+// JWT-mode's own secret key — deliberately a SEPARATE cache/key from
+// projectAuthSecret (password), never merged. Coexistence (both keys
+// present during a password→JWT migration) is by design: authType alone
+// (on the public plane) decides which one is consulted.
+export interface ProjectJwtSecret {
+  publicKeyPem: string;
+  version: number;
+}
+const projectJwtSecretCache = new TtlCache<ProjectJwtSecret>({ ttlMs: AUTH_TTL_MS, negativeTtlMs: NEGATIVE_TTL_MS });
+
+export async function getProjectJwtSecret(slug: string): Promise<ProjectJwtSecret | null> {
+  return readThrough(projectJwtSecretCache, `projectJwtSecret:${slug}`, () =>
+    redis!.get<ProjectJwtSecret>(`projectJwtSecret:${slug}`),
   );
 }

package/vendored/lib/docs-types.ts

@@ -846,12 +846,28 @@ export interface PasswordAuthConfig {
   private?: string[];
 }
 
+/**
+ * JWT authentication config. The verification key is generated and stored via
+ * the Jamdesk dashboard; this block only carries declarative opt-in, the
+ * customer login URL, and public path exceptions.
+ */
+export interface JwtAuthConfig {
+  /** Opt in to JWT auth. Site is only gated when this is true AND a signing key has been generated in the dashboard. */
+  enabled?: boolean;
+  /** Absolute https:// URL of your login flow. Unauthenticated visitors are redirected here with ?redirect=<path>. */
+  loginUrl?: string;
+  /** Paths or globs that bypass authentication. Supports '*' and '**'. */
+  public?: string[];
+}
+
 /**
  * Auth configuration for access control. Currently supports shared-password
- * protection; additional mechanisms may be added in future.
+ * protection and JWT authentication; additional mechanisms may be added in
+ * future.
  */
 export interface AuthConfig {
   password?: PasswordAuthConfig;
+  jwt?: JwtAuthConfig;
 }
 
 /**

package/vendored/lib/glob-match.ts

@@ -76,8 +76,62 @@ export function matchPublicPath(
       normalized = pathname.slice(5); // '/docs/' → '/' (keep leading slash)
     }
   }
+  // The main gate runs on the pretty path BEFORE the `.md` → markdown-export
+  // rewrite, so `/changelog.md` must match a public `/changelog` — otherwise
+  // the export of a public page over-gates while the HTML page is open.
+  // (resolveRequiredGroups strips the same suffix for the group lookup.)
+  if (normalized.length > 3 && normalized.endsWith('.md')) {
+    normalized = normalized.slice(0, -3);
+  }
 
   const { literals, regexes } = compilePublicPaths(publicPaths);
   if (literals.has(normalized)) return true;
   return regexes.some((re) => re.test(normalized));
 }
+
+const R2_CONTENT_RE = /^\/api\/r2\/[^/]+\/content\/(.+?)(?:\.mdx)?$/;
+// Direct hit on the raw-markdown export route: /api/markdown-export/{slug}/{page}.
+// The captured group is the root-relative page path (the middleware rewrite
+// already stripped any /docs prefix), so — like the /api/r2 branch — this shape
+// carries page content and must resolve group restrictions on it. Without this,
+// a direct external hit would pass the edge gate with no group requirement
+// resolved (the path doesn't look like a page path) and leak group-restricted
+// MDX to any authenticated user (and, gated on the wrong slug, cross-tenant).
+const MARKDOWN_EXPORT_RE = /^\/api\/markdown-export\/[^/]+\/(.+?)(?:\.md)?$/;
+
+/**
+ * Look up the required groups for a request path against the build-written
+ * groupsPaths map (keys are root-relative page slugs). Normalizes every path
+ * shape that serves page content: percent-encoding, hostAtDocs /docs prefix,
+ * trailing slash, markdown-export .md suffix, /api/r2 raw-MDX paths, and direct
+ * /api/markdown-export hits. Returns the required groups, or null when the path
+ * carries no restriction.
+ */
+export function resolveRequiredGroups(
+  pathname: string,
+  groupsPaths: Record<string, string[]>,
+  hostAtDocs: boolean,
+): string[] | null {
+  let p = pathname;
+  try { p = decodeURIComponent(p); } catch { /* keep raw — never throw in the gate */ }
+
+  const r2 = p.match(R2_CONTENT_RE);
+  const mdExport = p.match(MARKDOWN_EXPORT_RE);
+  if (r2) {
+    p = `/${r2[1]}`;
+  } else if (mdExport) {
+    // Page path already root-relative (rewrite stripped /docs); no hostAtDocs
+    // normalization, matching the /api/r2 branch.
+    p = `/${mdExport[1]}`;
+  } else {
+    if (hostAtDocs) {
+      if (p === '/docs') p = '/';
+      else if (p.startsWith('/docs/')) p = p.slice(5);
+    }
+    if (p.endsWith('.md')) p = p.slice(0, -3);
+    if (p.length > 1 && p.endsWith('/')) p = p.slice(0, -1);
+  }
+
+  const required = groupsPaths[p];
+  return Array.isArray(required) && required.length > 0 ? required : null;
+}

package/vendored/lib/jwt-auth-config.ts

@@ -0,0 +1,37 @@
+import type { DocsConfig } from './docs-types.js';
+
+/**
+ * Pure validation for the auth.jwt block. Returns config_error strings.
+ * Kept out of validate-config.ts so the CLI's parallel validator and the
+ * dashboard can reuse identical logic without dragging in Ajv.
+ */
+export function validateJwtAuth(config: DocsConfig): string[] {
+  const auth = config.auth as
+    | { password?: { enabled?: unknown }; jwt?: { enabled?: unknown; loginUrl?: unknown; public?: unknown } }
+    | undefined;
+  const jwt = auth?.jwt;
+  if (!jwt) return [];
+
+  const errors: string[] = [];
+  if (auth?.password?.enabled === true && jwt.enabled === true) {
+    errors.push('auth.password and auth.jwt cannot both be enabled — choose one authentication method');
+    return errors;
+  }
+  if (jwt.enabled === true) {
+    if (typeof jwt.loginUrl !== 'string' || jwt.loginUrl.length === 0) {
+      errors.push('auth.jwt.enabled requires auth.jwt.loginUrl (an absolute https:// URL of your login flow)');
+    } else {
+      let ok = false;
+      try {
+        ok = new URL(jwt.loginUrl).protocol === 'https:';
+      } catch { /* unparseable */ }
+      if (!ok) errors.push('auth.jwt.loginUrl must be an absolute https:// URL');
+    }
+  }
+  if (jwt.public !== undefined) {
+    const valid = Array.isArray(jwt.public) &&
+      jwt.public.every((p) => typeof p === 'string' && p.startsWith('/'));
+    if (!valid) errors.push('auth.jwt.public must be an array of path strings starting with /');
+  }
+  return errors;
+}