fix: address PR review — security and robustness fixes

- Path traversal: use safePath() guard for content file serving (dev + prod)
- XSS: escape </script> in __PAGE_DATA__ JSON via \u003c replacement
- SSRF: validate proxy path in apis-proxy handler
- Race condition: cancel stale search fetch responses
- useRef: add null initial value for React 19 compat
- Error messages: hide internal details in prod error responses
- Validate --adapter flag against known adapters

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rsbh

packages/chronicle/src/cli/commands/build.ts

@@ -13,6 +13,12 @@ export const buildCommand = new Command('build')
     const contentDir = resolveContentDir(options.content)
     const outDir = path.resolve(options.outDir)
 
+    const VALID_ADAPTERS = ['vercel']
+    if (options.adapter && !VALID_ADAPTERS.includes(options.adapter)) {
+      console.error(chalk.red(`Unknown adapter: ${options.adapter}. Valid adapters: ${VALID_ADAPTERS.join(', ')}`))
+      process.exit(1)
+    }
+
     process.env.CHRONICLE_PROJECT_ROOT = process.cwd()
     process.env.CHRONICLE_CONTENT_DIR = contentDir
 

packages/chronicle/src/components/ui/search.tsx

@@ -18,23 +18,27 @@ interface SearchResult {
 function useSearch(query: string) {
   const [results, setResults] = useState<SearchResult[]>([]);
   const [isLoading, setIsLoading] = useState(false);
-  const timerRef = useRef<ReturnType<typeof setTimeout>>();
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   useEffect(() => {
-    clearTimeout(timerRef.current);
+    let cancelled = false;
+    if (timerRef.current) clearTimeout(timerRef.current);
     timerRef.current = setTimeout(async () => {
       setIsLoading(true);
       try {
         const params = new URLSearchParams();
         if (query) params.set("query", query);
         const res = await fetch(`/api/search?${params}`);
-        setResults(await res.json());
+        if (!cancelled) setResults(await res.json());
       } catch {
-        setResults([]);
+        if (!cancelled) setResults([]);
       }
-      setIsLoading(false);
+      if (!cancelled) setIsLoading(false);
     }, 100);
-    return () => clearTimeout(timerRef.current);
+    return () => {
+      cancelled = true;
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
   }, [query]);
 
   return { results, isLoading };

packages/chronicle/src/server/dev.ts

@@ -5,6 +5,7 @@ import { createReadStream } from 'fs'
 import path from 'path'
 import chalk from 'chalk'
 import { createViteConfig } from './vite-config'
+import { safePath } from './utils/safe-path'
 
 export interface DevServerOptions {
   port: number
@@ -38,8 +39,8 @@ export async function startDevServer(options: DevServerOptions) {
       }
 
       // Serve static files from content dir (skip .md/.mdx)
-      const contentFile = path.join(contentDir, decodeURIComponent(url.split('?')[0]))
-      if (!url.endsWith('.md') && !url.endsWith('.mdx')) {
+      const contentFile = safePath(contentDir, url)
+      if (contentFile && !url.endsWith('.md') && !url.endsWith('.mdx')) {
         try {
           const stat = await fsPromises.stat(contentFile)
           if (stat.isFile()) {
@@ -119,7 +120,8 @@ export async function startDevServer(options: DevServerOptions) {
       template = await vite.transformIndexHtml(url, template)
 
       // Embed page data for client hydration
-      const dataScript = `<script>window.__PAGE_DATA__ = ${JSON.stringify(embeddedData)}</script>`
+      const safeJson = JSON.stringify(embeddedData).replace(/</g, '\\u003c')
+      const dataScript = `<script>window.__PAGE_DATA__ = ${safeJson}</script>`
       template = template.replace('<!--head-outlet-->', `<!--head-outlet-->${dataScript}`)
 
       const { render } = await vite.ssrLoadModule(path.resolve(root, 'src/server/entry-server.tsx'))

packages/chronicle/src/server/entry-prod.ts

@@ -9,6 +9,7 @@ import { loadConfig } from '@/lib/config'
 import { loadApiSpecs } from '@/lib/openapi'
 import { getPage, loadPageComponent, buildPageTree } from '@/lib/source'
 import { handleRequest } from './request-handler'
+import { safePath } from './utils/safe-path'
 
 export { render, matchRoute, loadConfig, loadApiSpecs, getPage, loadPageComponent, buildPageTree }
 
@@ -45,8 +46,8 @@ export async function startServer(options: { port: number; distDir: string }) {
 
       // Serve static files from content dir (skip .md/.mdx)
       const contentDir = process.env.CHRONICLE_CONTENT_DIR || process.cwd()
-      const contentFile = path.join(contentDir, decodeURIComponent(url.split('?')[0]))
-      if (!url.endsWith('.md') && !url.endsWith('.mdx')) {
+      const contentFile = safePath(contentDir, url)
+      if (contentFile && !url.endsWith('.md') && !url.endsWith('.mdx')) {
         try {
           const stat = await fsPromises.stat(contentFile)
           if (stat.isFile()) {
@@ -77,7 +78,7 @@ export async function startServer(options: { port: number; distDir: string }) {
     } catch (e) {
       console.error(e)
       res.statusCode = 500
-      res.end((e as Error).message)
+      res.end('Internal Server Error')
     }
   })
 

packages/chronicle/src/server/entry-vercel.ts

@@ -23,6 +23,6 @@ export default async function handler(req: IncomingMessage, res: ServerResponse)
   } catch (e) {
     console.error(e)
     res.statusCode = 500
-    res.end((e as Error).message)
+    res.end('Internal Server Error')
   }
 }

packages/chronicle/src/server/handlers/apis-proxy.ts

@@ -20,6 +20,11 @@ export async function handleApisProxy(req: Request): Promise<Response> {
     return Response.json({ error: `Unknown spec: ${specName}` }, { status: 404 })
   }
 
+  // Validate path doesn't contain protocol or escape the base URL
+  if (/^[a-z]+:\/\//i.test(path) || path.includes('..')) {
+    return Response.json({ error: 'Invalid path' }, { status: 400 })
+  }
+
   const url = spec.server.url + path
 
   try {

packages/chronicle/src/server/request-handler.ts

@@ -51,7 +51,8 @@ export async function handleRequest(url: string, options: RequestHandlerOptions)
 
   const html = render(url, { config, tree, page: pageData, apiSpecs })
 
-  const dataScript = `<script>window.__PAGE_DATA__ = ${JSON.stringify(embeddedData)}</script>`
+  const safeJson = JSON.stringify(embeddedData).replace(/</g, '\\u003c')
+  const dataScript = `<script>window.__PAGE_DATA__ = ${safeJson}</script>`
   const finalHtml = template
     .replace('<!--head-outlet-->', `<!--head-outlet-->${dataScript}`)
     .replace('<!--ssr-outlet-->', html)

packages/chronicle/src/server/utils/safe-path.ts

@@ -0,0 +1,14 @@
+import path from 'path'
+
+/**
+ * Resolve a URL path within a base directory, preventing path traversal.
+ * Returns null if the resolved path escapes the base directory.
+ */
+export function safePath(baseDir: string, urlPath: string): string | null {
+  const decoded = decodeURIComponent(urlPath.split('?')[0])
+  const resolved = path.resolve(baseDir, '.' + decoded)
+  if (!resolved.startsWith(path.resolve(baseDir) + path.sep) && resolved !== path.resolve(baseDir)) {
+    return null
+  }
+  return resolved
+}