mcp-web-validator 1.0.0 → 1.2.1

package/dist/screenshot.js

@@ -1,11 +1,113 @@
 import puppeteer from "puppeteer";
 import * as path from "path";
 import * as fs from "fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { assertPublicHttpUrl, getErrorMessage } from "./network.js";
 const DEFAULT_VIEWPORTS = [
     { name: "desktop", width: 1440, height: 900 },
     { name: "tablet", width: 768, height: 1024 },
     { name: "mobile", width: 375, height: 812 }
 ];
+const MAX_VIEWPORTS = 10;
+const MIN_VIEWPORT_DIMENSION = 100;
+const MAX_VIEWPORT_DIMENSION = 7_680;
+const SAFE_VIEWPORT_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+const NAVIGATION_TIMEOUT_MS = 30_000;
+export const SCREENSHOT_HEADLESS_MODE = "shell";
+function validateViewports(viewports) {
+    if (viewports.length === 0 || viewports.length > MAX_VIEWPORTS) {
+        throw new Error(`Between 1 and ${MAX_VIEWPORTS} viewports are required`);
+    }
+    const outputNames = new Set();
+    return viewports.map((viewport, index) => {
+        if (!viewport || typeof viewport !== "object") {
+            throw new Error(`Viewport #${index + 1} must be an object`);
+        }
+        if (typeof viewport.name !== "string" || !SAFE_VIEWPORT_NAME.test(viewport.name)) {
+            throw new Error(`Viewport #${index + 1} name must match ${SAFE_VIEWPORT_NAME.source}`);
+        }
+        for (const [label, value] of [["width", viewport.width], ["height", viewport.height]]) {
+            if (!Number.isSafeInteger(value)
+                || value < MIN_VIEWPORT_DIMENSION
+                || value > MAX_VIEWPORT_DIMENSION) {
+                throw new Error(`Viewport #${index + 1} ${label} must be an integer between ${MIN_VIEWPORT_DIMENSION} and ${MAX_VIEWPORT_DIMENSION}`);
+            }
+        }
+        const outputName = `${viewport.name}_${viewport.width}x${viewport.height}.png`.toLowerCase();
+        if (outputNames.has(outputName)) {
+            throw new Error(`Duplicate viewport output filename: ${outputName}`);
+        }
+        outputNames.add(outputName);
+        return { name: viewport.name, width: viewport.width, height: viewport.height };
+    });
+}
+function resolveContainedOutputPath(outputDirectory, fileName) {
+    const outputPath = path.resolve(outputDirectory, fileName);
+    const relativePath = path.relative(outputDirectory, outputPath);
+    if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+        throw new Error("Screenshot output path escapes the requested output directory");
+    }
+    return outputPath;
+}
+function isPathWithinDirectory(directory, filePath) {
+    const relativePath = path.relative(directory, filePath);
+    return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
+}
+async function assertLocalScreenshotRequestAllowed(requestUrl, localDirectory) {
+    if (requestUrl.hostname) {
+        throw new Error("Blocked local file request with a host name");
+    }
+    let resolvedPath;
+    try {
+        resolvedPath = await fs.realpath(fileURLToPath(requestUrl));
+    }
+    catch (error) {
+        throw new Error(`Blocked local file request: ${getErrorMessage(error)}`);
+    }
+    if (!isPathWithinDirectory(localDirectory, resolvedPath)) {
+        throw new Error("Blocked local file request outside the selected file directory");
+    }
+}
+async function assertScreenshotRequestAllowed(requestUrl, localDirectory) {
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(requestUrl);
+    }
+    catch {
+        throw new Error("Blocked invalid page request URL");
+    }
+    if (parsedUrl.protocol === "http:" || parsedUrl.protocol === "https:") {
+        await assertPublicHttpUrl(parsedUrl);
+        return;
+    }
+    if (parsedUrl.protocol === "data:" || parsedUrl.protocol === "blob:") {
+        return;
+    }
+    if (parsedUrl.protocol === "file:" && localDirectory) {
+        await assertLocalScreenshotRequestAllowed(parsedUrl, localDirectory);
+        return;
+    }
+    throw new Error(`Blocked unsupported page request protocol ${parsedUrl.protocol}`);
+}
+async function resolveScreenshotRequest(request, localDirectory, onBlocked) {
+    if (request.isInterceptResolutionHandled()) {
+        return;
+    }
+    try {
+        await assertScreenshotRequestAllowed(request.url(), localDirectory);
+        if (request.isInterceptResolutionHandled()) {
+            return;
+        }
+        await request.continue();
+    }
+    catch (error) {
+        onBlocked(getErrorMessage(error));
+        if (request.isInterceptResolutionHandled()) {
+            return;
+        }
+        await request.abort("blockedbyclient");
+    }
+}
 /**
  * Captures screenshots of a local HTML file or remote URL at different viewport sizes.
  * @param targetPath Local file path or HTTP(S) URL
@@ -13,23 +115,49 @@ const DEFAULT_VIEWPORTS = [
  * @param customViewports Optional custom viewport settings
  */
 export async function captureScreenshots(targetPath, outputDirectory, customViewports) {
-    const viewports = customViewports && customViewports.length > 0 ? customViewports : DEFAULT_VIEWPORTS;
+    if (typeof targetPath !== "string" || targetPath.trim() === "") {
+        throw new Error("targetPath must be a non-empty string");
+    }
+    if (typeof outputDirectory !== "string" || outputDirectory.trim() === "") {
+        throw new Error("outputDirectory must be a non-empty string");
+    }
+    const viewports = validateViewports(customViewports && customViewports.length > 0 ? customViewports : DEFAULT_VIEWPORTS);
+    const resolvedOutputDirectory = path.resolve(outputDirectory);
     // Resolve target to file:// URL if it is a local file path
-    let targetUrl = targetPath;
-    if (!targetPath.startsWith("http://") && !targetPath.startsWith("https://")) {
+    let targetUrl;
+    let localDirectory;
+    if (/^https?:\/\//i.test(targetPath)) {
+        targetUrl = (await assertPublicHttpUrl(targetPath)).href;
+    }
+    else {
         const absolutePath = path.resolve(targetPath);
-        targetUrl = `file://${absolutePath.replace(/\\/g, "/")}`;
+        const resolvedPath = await fs.realpath(absolutePath);
+        const stats = await fs.stat(resolvedPath);
+        if (!stats.isFile()) {
+            throw new Error(`Screenshot target is not a regular file: ${resolvedPath}`);
+        }
+        localDirectory = path.dirname(resolvedPath);
+        targetUrl = pathToFileURL(resolvedPath).href;
     }
     // Ensure output directory exists
-    await fs.mkdir(outputDirectory, { recursive: true });
-    // Launch browser in headless mode
+    await fs.mkdir(resolvedOutputDirectory, { recursive: true });
+    // Launch Puppeteer's bundled headless shell.
     const browser = await puppeteer.launch({
-        headless: true,
-        args: ["--no-sandbox", "--disable-setuid-sandbox"]
+        headless: SCREENSHOT_HEADLESS_MODE,
     });
     const results = [];
     try {
         const page = await browser.newPage();
+        page.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
+        let blockedRequestMessage;
+        await page.setRequestInterception(true);
+        page.on("request", (request) => {
+            void resolveScreenshotRequest(request, localDirectory, (message) => {
+                blockedRequestMessage ??= message;
+            }).catch(() => {
+                // Puppeteer will surface navigation failures; avoid an unhandled listener rejection.
+            });
+        });
         for (const vp of viewports) {
             await page.setViewport({
                 width: vp.width,
@@ -37,14 +165,22 @@ export async function captureScreenshots(targetPath, outputDirectory, customView
                 deviceScaleFactor: 1
             });
             // Load URL (wait until network is idle or DOM loaded)
-            await page.goto(targetUrl, {
-                waitUntil: "domcontentloaded",
-                timeout: 30000
-            });
+            try {
+                await page.goto(targetUrl, {
+                    waitUntil: "domcontentloaded",
+                    timeout: NAVIGATION_TIMEOUT_MS,
+                });
+            }
+            catch (error) {
+                if (blockedRequestMessage) {
+                    throw new Error(`Screenshot navigation blocked: ${blockedRequestMessage}`);
+                }
+                throw new Error(`Screenshot navigation failed: ${getErrorMessage(error)}`);
+            }
             // Short wait for any animations or layout adjustments to settle
             await new Promise((resolve) => setTimeout(resolve, 500));
             const fileName = `${vp.name}_${vp.width}x${vp.height}.png`;
-            const outputPath = path.join(outputDirectory, fileName);
+            const outputPath = resolveContainedOutputPath(resolvedOutputDirectory, fileName);
             await page.screenshot({
                 path: outputPath,
                 fullPage: false // Captures above the fold viewport
@@ -53,7 +189,7 @@ export async function captureScreenshots(targetPath, outputDirectory, customView
                 viewportName: vp.name,
                 width: vp.width,
                 height: vp.height,
-                outputPath: path.resolve(outputPath)
+                outputPath
             });
         }
     }

package/dist/screenshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../src/screenshot.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../src/screenshot.ts"],"names":[],"mappings":"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","sourcesContent":["import puppeteer from \"puppeteer\";\nimport * as path from \"path\";\nimport * as fs from \"fs/promises\";\nimport { fileURLToPath, pathToFileURL } from \"node:url\";\nimport { assertPublicHttpUrl, getErrorMessage } from \"./network.js\";\n\nexport interface ViewportConfig {\n  name: string;\n  width: number;\n  height: number;\n}\n\nexport interface ScreenshotResult {\n  viewportName: string;\n  width: number;\n  height: number;\n  outputPath: string;\n}\n\nconst DEFAULT_VIEWPORTS: ViewportConfig[] = [\n  { name: \"desktop\", width: 1440, height: 900 },\n  { name: \"tablet\", width: 768, height: 1024 },\n  { name: \"mobile\", width: 375, height: 812 }\n];\n\nconst MAX_VIEWPORTS = 10;\nconst MIN_VIEWPORT_DIMENSION = 100;\nconst MAX_VIEWPORT_DIMENSION = 7_680;\nconst SAFE_VIEWPORT_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;\nconst NAVIGATION_TIMEOUT_MS = 30_000;\n\nexport const SCREENSHOT_HEADLESS_MODE = \"shell\" as const;\n\ninterface InterceptedRequest {\n  url(): string;\n  isInterceptResolutionHandled(): boolean;\n  continue(): Promise<unknown>;\n  abort(errorCode?: string): Promise<unknown>;\n}\n\nfunction validateViewports(viewports: ViewportConfig[]): ViewportConfig[] {\n  if (viewports.length === 0 || viewports.length > MAX_VIEWPORTS) {\n    throw new Error(`Between 1 and ${MAX_VIEWPORTS} viewports are required`);\n  }\n\n  const outputNames = new Set<string>();\n  return viewports.map((viewport, index) => {\n    if (!viewport || typeof viewport !== \"object\") {\n      throw new Error(`Viewport #${index + 1} must be an object`);\n    }\n    if (typeof viewport.name !== \"string\" || !SAFE_VIEWPORT_NAME.test(viewport.name)) {\n      throw new Error(\n        `Viewport #${index + 1} name must match ${SAFE_VIEWPORT_NAME.source}`,\n      );\n    }\n    for (const [label, value] of [[\"width\", viewport.width], [\"height\", viewport.height]] as const) {\n      if (\n        !Number.isSafeInteger(value)\n        || value < MIN_VIEWPORT_DIMENSION\n        || value > MAX_VIEWPORT_DIMENSION\n      ) {\n        throw new Error(\n          `Viewport #${index + 1} ${label} must be an integer between ${MIN_VIEWPORT_DIMENSION} and ${MAX_VIEWPORT_DIMENSION}`,\n        );\n      }\n    }\n\n    const outputName = `${viewport.name}_${viewport.width}x${viewport.height}.png`.toLowerCase();\n    if (outputNames.has(outputName)) {\n      throw new Error(`Duplicate viewport output filename: ${outputName}`);\n    }\n    outputNames.add(outputName);\n    return { name: viewport.name, width: viewport.width, height: viewport.height };\n  });\n}\n\nfunction resolveContainedOutputPath(outputDirectory: string, fileName: string): string {\n  const outputPath = path.resolve(outputDirectory, fileName);\n  const relativePath = path.relative(outputDirectory, outputPath);\n  if (relativePath.startsWith(\"..\") || path.isAbsolute(relativePath)) {\n    throw new Error(\"Screenshot output path escapes the requested output directory\");\n  }\n  return outputPath;\n}\n\nfunction isPathWithinDirectory(directory: string, filePath: string): boolean {\n  const relativePath = path.relative(directory, filePath);\n  return relativePath === \"\" || (!relativePath.startsWith(\"..\") && !path.isAbsolute(relativePath));\n}\n\nasync function assertLocalScreenshotRequestAllowed(requestUrl: URL, localDirectory: string): Promise<void> {\n  if (requestUrl.hostname) {\n    throw new Error(\"Blocked local file request with a host name\");\n  }\n\n  let resolvedPath: string;\n  try {\n    resolvedPath = await fs.realpath(fileURLToPath(requestUrl));\n  } catch (error: unknown) {\n    throw new Error(`Blocked local file request: ${getErrorMessage(error)}`);\n  }\n\n  if (!isPathWithinDirectory(localDirectory, resolvedPath)) {\n    throw new Error(\"Blocked local file request outside the selected file directory\");\n  }\n}\n\nasync function assertScreenshotRequestAllowed(requestUrl: string, localDirectory?: string): Promise<void> {\n  let parsedUrl: URL;\n  try {\n    parsedUrl = new URL(requestUrl);\n  } catch {\n    throw new Error(\"Blocked invalid page request URL\");\n  }\n\n  if (parsedUrl.protocol === \"http:\" || parsedUrl.protocol === \"https:\") {\n    await assertPublicHttpUrl(parsedUrl);\n    return;\n  }\n\n  if (parsedUrl.protocol === \"data:\" || parsedUrl.protocol === \"blob:\") {\n    return;\n  }\n\n  if (parsedUrl.protocol === \"file:\" && localDirectory) {\n    await assertLocalScreenshotRequestAllowed(parsedUrl, localDirectory);\n    return;\n  }\n\n  throw new Error(`Blocked unsupported page request protocol ${parsedUrl.protocol}`);\n}\n\nasync function resolveScreenshotRequest(\n  request: InterceptedRequest,\n  localDirectory: string | undefined,\n  onBlocked: (message: string) => void,\n): Promise<void> {\n  if (request.isInterceptResolutionHandled()) {\n    return;\n  }\n\n  try {\n    await assertScreenshotRequestAllowed(request.url(), localDirectory);\n    if (request.isInterceptResolutionHandled()) {\n      return;\n    }\n    await request.continue();\n  } catch (error: unknown) {\n    onBlocked(getErrorMessage(error));\n    if (request.isInterceptResolutionHandled()) {\n      return;\n    }\n    await request.abort(\"blockedbyclient\");\n  }\n}\n\n/**\n * Captures screenshots of a local HTML file or remote URL at different viewport sizes.\n * @param targetPath Local file path or HTTP(S) URL\n * @param outputDirectory Absolute path to save screenshots\n * @param customViewports Optional custom viewport settings\n */\nexport async function captureScreenshots(\n  targetPath: string,\n  outputDirectory: string,\n  customViewports?: ViewportConfig[]\n): Promise<ScreenshotResult[]> {\n  if (typeof targetPath !== \"string\" || targetPath.trim() === \"\") {\n    throw new Error(\"targetPath must be a non-empty string\");\n  }\n  if (typeof outputDirectory !== \"string\" || outputDirectory.trim() === \"\") {\n    throw new Error(\"outputDirectory must be a non-empty string\");\n  }\n\n  const viewports = validateViewports(\n    customViewports && customViewports.length > 0 ? customViewports : DEFAULT_VIEWPORTS,\n  );\n  const resolvedOutputDirectory = path.resolve(outputDirectory);\n\n  // Resolve target to file:// URL if it is a local file path\n  let targetUrl: string;\n  let localDirectory: string | undefined;\n  if (/^https?:\\/\\//i.test(targetPath)) {\n    targetUrl = (await assertPublicHttpUrl(targetPath)).href;\n  } else {\n    const absolutePath = path.resolve(targetPath);\n    const resolvedPath = await fs.realpath(absolutePath);\n    const stats = await fs.stat(resolvedPath);\n    if (!stats.isFile()) {\n      throw new Error(`Screenshot target is not a regular file: ${resolvedPath}`);\n    }\n    localDirectory = path.dirname(resolvedPath);\n    targetUrl = pathToFileURL(resolvedPath).href;\n  }\n\n  // Ensure output directory exists\n  await fs.mkdir(resolvedOutputDirectory, { recursive: true });\n\n  // Launch Puppeteer's bundled headless shell.\n  const browser = await puppeteer.launch({\n    headless: SCREENSHOT_HEADLESS_MODE,\n  });\n\n  const results: ScreenshotResult[] = [];\n\n  try {\n    const page = await browser.newPage();\n    page.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);\n\n    let blockedRequestMessage: string | undefined;\n    await page.setRequestInterception(true);\n    page.on(\"request\", (request) => {\n      void resolveScreenshotRequest(request, localDirectory, (message) => {\n        blockedRequestMessage ??= message;\n      }).catch(() => {\n        // Puppeteer will surface navigation failures; avoid an unhandled listener rejection.\n      });\n    });\n\n    for (const vp of viewports) {\n      await page.setViewport({\n        width: vp.width,\n        height: vp.height,\n        deviceScaleFactor: 1\n      });\n\n      // Load URL (wait until network is idle or DOM loaded)\n      try {\n        await page.goto(targetUrl, {\n          waitUntil: \"domcontentloaded\",\n          timeout: NAVIGATION_TIMEOUT_MS,\n        });\n      } catch (error: unknown) {\n        if (blockedRequestMessage) {\n          throw new Error(`Screenshot navigation blocked: ${blockedRequestMessage}`);\n        }\n        throw new Error(`Screenshot navigation failed: ${getErrorMessage(error)}`);\n      }\n\n      // Short wait for any animations or layout adjustments to settle\n      await new Promise((resolve) => setTimeout(resolve, 500));\n\n      const fileName = `${vp.name}_${vp.width}x${vp.height}.png`;\n      const outputPath = resolveContainedOutputPath(resolvedOutputDirectory, fileName);\n\n      await page.screenshot({\n        path: outputPath,\n        fullPage: false // Captures above the fold viewport\n      });\n\n      results.push({\n        viewportName: vp.name,\n        width: vp.width,\n        height: vp.height,\n        outputPath\n      });\n    }\n  } finally {\n    await browser.close();\n  }\n\n  return results;\n}\n"]}

package/dist/seo-auditor.d.ts

@@ -1,3 +1,5 @@
+export declare const MAX_AUDIT_ISSUES = 200;
+export declare const MAX_LINKS_TO_CHECK = 25;
 export interface SEOIssue {
     severity: "error" | "warning" | "info";
     category: "SEO" | "Schema" | "BrokenLinks" | "Accessibility";
@@ -10,15 +12,22 @@ export interface LinkStatus {
     ok: boolean;
     message?: string;
 }
+export interface AuditDetails {
+    issues: SEOIssue[];
+    totalIssues: number;
+    truncated: boolean;
+}
 /**
  * Audits technical SEO and accessibility basics on HTML content using Cheerio
  */
+export declare function auditSeoMetadataDetailed(htmlContent: string): AuditDetails;
 export declare function auditSeoMetadata(htmlContent: string): SEOIssue[];
 /**
  * Parses and validates JSON-LD Schema markup
  */
+export declare function validateSchemaMarkupDetailed(htmlContent: string): AuditDetails;
 export declare function validateSchemaMarkup(htmlContent: string): SEOIssue[];
 /**
- * Extracts and tests all links inside the HTML content for broken links (4xx / 5xx)
+ * Extracts and tests links, treating 3xx responses as reachable redirects and 4xx/5xx as broken.
  */
-export declare function checkBrokenLinks(htmlContent: string, baseUrl?: string): Promise<LinkStatus[]>;
+export declare function checkBrokenLinks(htmlContent: string, baseUrl?: string, maxLinks?: number): Promise<LinkStatus[]>;