@aravindc26/velu 0.13.5 → 0.13.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aravindc26/velu",
-  "version": "0.13.5",
+  "version": "0.13.7",
   "description": "A modern documentation site generator powered by Markdown and JSON configuration",
   "type": "module",
   "license": "MIT",

package/src/engine/app/_preview/[sessionId]/[...slug]/page.tsx

@@ -141,15 +141,10 @@ function prefixMdxComponentLinks(
 export default async function PreviewPage({ params }: PageProps) {
   const { sessionId, slug } = await params;
 
-  console.log(`[PREVIEW:page] START session=${sessionId} slug=${slug.join('/')}`);
-
   const src = await getSessionSource(sessionId);
   const page = src.getPage(slug);
 
-  if (!page) {
-    console.log(`[PREVIEW:page] Page NOT FOUND for slug=${slug.join('/')}`);
-    notFound();
-  }
+  if (!page) notFound();
 
   const pageDataRecord = page.data as unknown as Record<string, unknown>;
 
@@ -159,22 +154,16 @@ export default async function PreviewPage({ params }: PageProps) {
   let pageToc: any;
 
   if (typeof loadFn === 'function') {
-    console.log(`[PREVIEW:page] Calling load() for slug=${slug.join('/')}`);
     const loaded = await loadFn();
     MDX = loaded.body;
     pageToc = loaded.toc;
-    console.log(`[PREVIEW:page] load() returned MDX=${typeof MDX} toc=${typeof pageToc}`);
   } else {
     // Fallback: pre-compiled entry (shouldn't happen in preview mode, but safe)
-    console.log(`[PREVIEW:page] No load() — using pre-compiled body for slug=${slug.join('/')}`);
     MDX = pageDataRecord.body as any;
     pageToc = pageDataRecord.toc as any;
   }
 
-  if (typeof MDX !== 'function') {
-    console.log(`[PREVIEW:page] MDX is not a function (type=${typeof MDX}), returning 404`);
-    notFound();
-  }
+  if (typeof MDX !== 'function') notFound();
 
   const configSource = loadSessionConfigSource(sessionId);
   const footerSocials = configSource ? getFooterSocials(configSource) : [];
@@ -186,7 +175,6 @@ export default async function PreviewPage({ params }: PageProps) {
   if (pageInfo?.fullPath) {
     try {
       effectiveMarkdown = readFileSync(pageInfo.fullPath, 'utf-8');
-      console.log(`[PREVIEW:page] Read markdown from ${pageInfo.fullPath} (${effectiveMarkdown.length} chars, first 120: ${JSON.stringify(effectiveMarkdown.slice(0, 120))})`);
     } catch { /* file may not exist */ }
   }
 

package/src/engine/lib/preview-auth.ts

@@ -1,16 +1,72 @@
 /**
  * Shared API authentication via PREVIEW_API_SECRET.
  */
+import { createHmac, timingSafeEqual } from 'crypto';
 import { NextRequest } from 'next/server';
 
 const PREVIEW_API_SECRET = process.env.PREVIEW_API_SECRET || '';
 
+export function getPreviewSecret(): string {
+  return PREVIEW_API_SECRET;
+}
+
 export function verifyApiSecret(request: NextRequest): boolean {
   if (!PREVIEW_API_SECRET) return true; // No secret configured — allow all
   const header = request.headers.get('x-preview-secret') || '';
   return header === PREVIEW_API_SECRET;
 }
 
+/**
+ * Verify an HMAC-signed preview token.
+ *
+ * Token format: `{base64url_hmac}.{sessionId}:{unix_expiry}`
+ *
+ * Returns `{ valid: true, expiry }` when the token is authentic, matches the
+ * expected session ID, and has not expired. Returns `{ valid: false, expiry: 0 }`
+ * otherwise.
+ */
+export function verifyPreviewToken(
+  token: string,
+  expectedSessionId: string,
+): { valid: boolean; expiry: number } {
+  const fail = { valid: false, expiry: 0 };
+  if (!PREVIEW_API_SECRET) return { valid: true, expiry: 0 }; // No secret — allow all
+
+  const dotIdx = token.indexOf('.');
+  if (dotIdx === -1) return fail;
+
+  const sigB64 = token.slice(0, dotIdx);
+  const payload = token.slice(dotIdx + 1);
+
+  // Payload must be "{sessionId}:{expiry}"
+  const colonIdx = payload.indexOf(':');
+  if (colonIdx === -1) return fail;
+
+  const sessionId = payload.slice(0, colonIdx);
+  const expiryStr = payload.slice(colonIdx + 1);
+
+  if (sessionId !== expectedSessionId) return fail;
+
+  const expiry = parseInt(expiryStr, 10);
+  if (isNaN(expiry) || expiry < Math.floor(Date.now() / 1000)) return fail;
+
+  // Recompute HMAC and compare in constant time
+  const expectedSig = createHmac('sha256', PREVIEW_API_SECRET)
+    .update(payload)
+    .digest('base64url')
+    // Strip padding to match Python's rstrip(b"=")
+    .replace(/=+$/, '');
+
+  // Ensure both are the same length before timingSafeEqual
+  const sigBuf = Buffer.from(sigB64, 'utf8');
+  const expectedBuf = Buffer.from(expectedSig, 'utf8');
+  if (sigBuf.length !== expectedBuf.length) return fail;
+
+  if (!timingSafeEqual(sigBuf, expectedBuf)) return fail;
+
+  return { valid: true, expiry };
+}
+
 export function unauthorizedResponse() {
   return Response.json({ error: 'Unauthorized' }, { status: 401 });
 }

package/src/engine/lib/preview-content.ts

@@ -755,10 +755,9 @@ export function syncSessionFile(
   const workspaceDir = join(WORKSPACE_DIR, sessionId);
   const outputDir = join(PREVIEW_CONTENT_DIR, sessionId);
 
-  console.log(`[PREVIEW:syncFile] session=${sessionId} file=${filePath} workspace=${workspaceDir} output=${outputDir}`);
+  console.log(`[PREVIEW:syncFile] session=${sessionId} file=${filePath}`);
 
   if (filePath === PRIMARY_CONFIG_NAME || filePath === LEGACY_CONFIG_NAME) {
-    console.log(`[PREVIEW:syncFile] Config file changed — regenerating all content`);
     generateSessionContent(sessionId);
     return { synced: true };
   }
@@ -780,13 +779,9 @@ export function syncSessionFile(
     srcPath = join(workspaceDir, `${stripped}.md`);
   }
   if (!existsSync(srcPath)) {
-    console.log(`[PREVIEW:syncFile] Source file NOT FOUND at any candidate path for ${filePath}`);
     return { synced: false };
   }
 
-  const srcContent = readFileSync(srcPath, 'utf-8');
-  console.log(`[PREVIEW:syncFile] Source file: ${srcPath} (${srcContent.length} chars, first 120: ${JSON.stringify(srcContent.slice(0, 120))})`);
-
   try {
     const { config } = loadConfig(workspaceDir);
     const artifacts = buildArtifacts(config, workspaceDir);
@@ -796,22 +791,15 @@ export function syncSessionFile(
 
     if (mapping) {
       const destPath = join(outputDir, `${mapping.dest}.mdx`);
-      console.log(`[PREVIEW:syncFile] Mapped: ${stripped} -> ${mapping.dest}, writing to ${destPath}`);
       processPage(srcPath, destPath, stripped, variables, sessionId);
-      const written = readFileSync(destPath, 'utf-8');
-      console.log(`[PREVIEW:syncFile] Written dest (${written.length} chars, first 120: ${JSON.stringify(written.slice(0, 120))})`);
       return { synced: true };
     }
-    console.log(`[PREVIEW:syncFile] No mapping found for ${stripped} in pageMap (${artifacts.pageMap.length} entries)`);
-  } catch (err) {
-    console.log(`[PREVIEW:syncFile] Mapping lookup failed, falling through to direct copy:`, err instanceof Error ? err.message : err);
+  } catch {
+    // Fall through to direct copy
   }
 
   const destPath = join(outputDir, `${stripped}.mdx`);
-  console.log(`[PREVIEW:syncFile] Direct copy: ${srcPath} -> ${destPath}`);
   processPage(srcPath, destPath, stripped, variables, sessionId);
-  const written = readFileSync(destPath, 'utf-8');
-  console.log(`[PREVIEW:syncFile] Written dest (${written.length} chars, first 120: ${JSON.stringify(written.slice(0, 120))})`);
   return { synced: true };
 }
 

package/src/engine/lib/preview-source.ts

@@ -9,7 +9,7 @@
  * Used only in preview mode (PREVIEW_MODE=true) — production builds still use
  * the standard `source.ts` with build-time collections.
  */
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { loader } from 'fumadocs-core/source';
 import { dynamic } from 'fumadocs-mdx/runtime/dynamic';
@@ -31,6 +31,30 @@ function log(tag: string, msg: string, data?: Record<string, unknown>) {
 
 // ── Cache ──────────────────────────────────────────────────────────────────
 
+// File-based invalidation signal. Next.js bundles API routes and page routes
+// into separate module instances, so in-memory invalidation from the sync/init
+// route handler does NOT clear the cache seen by the page renderer. Instead,
+// the invalidation writes a timestamp to a file on disk which both sides can see.
+const INVALIDATION_DIR = join(PREVIEW_CONTENT_DIR, '.invalidation');
+
+function getInvalidationPath(sessionId: string): string {
+  return join(INVALIDATION_DIR, `${sessionId}.stamp`);
+}
+
+function readInvalidationStamp(sessionId: string): number {
+  const p = getInvalidationPath(sessionId);
+  try {
+    return Number(readFileSync(p, 'utf-8').trim()) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+function writeInvalidationStamp(sessionId: string): void {
+  mkdirSync(INVALIDATION_DIR, { recursive: true });
+  writeFileSync(getInvalidationPath(sessionId), String(Date.now()), 'utf-8');
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const sourceCache = new Map<string, { source: any; createdAt: number }>();
 
@@ -154,11 +178,17 @@ function scanContentDir(sessionDir: string): {
 export async function getSessionSource(sessionId: string) {
   const cached = sourceCache.get(sessionId);
   if (cached) {
-    const age = Date.now() - cached.createdAt;
-    log('source', `Cache HIT for session ${sessionId}`, { ageMs: age });
-    return cached.source;
+    const stamp = readInvalidationStamp(sessionId);
+    if (stamp <= cached.createdAt) {
+      const age = Date.now() - cached.createdAt;
+      log('source', `Cache HIT for session ${sessionId}`, { ageMs: age });
+      return cached.source;
+    }
+    log('source', `Cache STALE for session ${sessionId} (stamp=${stamp} > created=${cached.createdAt}), rebuilding`);
+    sourceCache.delete(sessionId);
+  } else {
+    log('source', `Cache MISS for session ${sessionId}`);
   }
-  log('source', `Cache MISS for session ${sessionId}`);
 
   const sessionDir = join(PREVIEW_CONTENT_DIR, sessionId);
   if (!existsSync(sessionDir)) {
@@ -176,15 +206,6 @@ export async function getSessionSource(sessionId: string) {
   log('source', `Scanned ${sessionDir}`, {
     entryCount: entries.length,
     metaFileCount: Object.keys(metaFiles).length,
-    files: entries.map((e) => {
-      const stat = statSync(e.info.fullPath, { throwIfNoEntry: false });
-      return {
-        path: e.info.path,
-        title: e.data.title,
-        sizeBytes: stat?.size,
-        mtimeMs: stat?.mtimeMs,
-      };
-    }),
   });
 
   const collection = await dyn.docs('docs', sessionDir, metaFiles, entries);
@@ -222,12 +243,15 @@ export async function getSessionSource(sessionId: string) {
 
 /**
  * Invalidate the cached source for a session.
- * Call after content generation or sync so the next request re-scans.
+ * Writes a file-based timestamp so that ALL Next.js module instances
+ * (API routes AND page routes) see the invalidation, even though they
+ * run in separate bundles with separate in-memory Maps.
  */
 export function invalidateSessionSource(sessionId: string): void {
   const had = sourceCache.has(sessionId);
   sourceCache.delete(sessionId);
-  log('invalidate', `session=${sessionId} hadCache=${had} remainingKeys=[${[...sourceCache.keys()].join(',')}]`);
+  writeInvalidationStamp(sessionId);
+  log('invalidate', `session=${sessionId} hadCache=${had} wroteStamp=true`);
 }
 
 /**

package/src/engine/middleware.ts

@@ -0,0 +1,91 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getPreviewSecret, verifyPreviewToken } from './lib/preview-auth';
+
+/**
+ * Next.js middleware that enforces HMAC-signed token authentication for
+ * preview page routes.
+ *
+ * Flow:
+ *  1. Requests with `x-preview-secret` header pass through (server-to-server API calls).
+ *  2. Extract sessionId from the URL path (`/{sessionId}/...`).
+ *  3. If `?token=` query param is present: validate HMAC, set an HttpOnly cookie,
+ *     redirect to the same URL without the token (keeps browser history clean).
+ *  4. If a valid `__velu_preview_{sessionId}` cookie exists: allow.
+ *  5. Otherwise: 403.
+ */
+export function middleware(request: NextRequest) {
+  const secret = getPreviewSecret();
+
+  // No secret configured — allow everything (dev / local)
+  if (!secret) return NextResponse.next();
+
+  // Server-to-server API calls use the x-preview-secret header — skip page auth
+  if (request.headers.get('x-preview-secret')) {
+    return NextResponse.next();
+  }
+
+  const { pathname } = request.nextUrl;
+
+  // Extract sessionId: first path segment after leading slash
+  const segments = pathname.split('/').filter(Boolean);
+  if (segments.length === 0) return NextResponse.next();
+
+  // Skip Next.js internal and static paths
+  const first = segments[0];
+  if (first === '_next' || first === 'api') return NextResponse.next();
+
+  // sessionId should be numeric
+  const sessionId = first;
+  if (!/^\d+$/.test(sessionId)) return NextResponse.next();
+
+  // --- Token in query string: validate, set cookie, redirect to clean URL ---
+  const tokenParam = request.nextUrl.searchParams.get('token');
+  if (tokenParam) {
+    const { valid, expiry } = verifyPreviewToken(tokenParam, sessionId);
+    if (!valid) {
+      return new NextResponse('Forbidden', { status: 403 });
+    }
+
+    // Redirect to the same URL without the token
+    const cleanUrl = request.nextUrl.clone();
+    cleanUrl.searchParams.delete('token');
+    const response = NextResponse.redirect(cleanUrl);
+
+    // Compute remaining TTL for cookie maxAge
+    const now = Math.floor(Date.now() / 1000);
+    const maxAge = expiry > 0 ? expiry - now : 86400;
+
+    response.cookies.set(`__velu_preview_${sessionId}`, tokenParam, {
+      httpOnly: true,
+      secure: true,
+      sameSite: 'none', // Required for cross-origin iframe
+      path: `/${sessionId}`,
+      maxAge,
+    });
+
+    return response;
+  }
+
+  // --- Cookie: validate existing token stored in cookie ---
+  const cookie = request.cookies.get(`__velu_preview_${sessionId}`);
+  if (cookie) {
+    const { valid } = verifyPreviewToken(cookie.value, sessionId);
+    if (valid) return NextResponse.next();
+  }
+
+  return new NextResponse('Forbidden', { status: 403 });
+}
+
+// Use Node.js runtime so we can access the crypto module for HMAC verification
+export const runtime = 'nodejs';
+
+export const config = {
+  matcher: [
+    /*
+     * Match all request paths except:
+     * - _next (Next.js internals)
+     * - favicon.ico, robots.txt, sitemap.xml (static meta)
+     */
+    '/((?!_next|favicon\\.ico|robots\\.txt|sitemap\\.xml).*)',
+  ],
+};