@icjia/contrastcap 0.1.1 → 0.1.4

package/README.md

@@ -199,6 +199,9 @@ Server + axe-core + Playwright versions, plus a non-blocking npm update check.
 | `CONTRASTCAP_MAX_CONCURRENT` | `2` | Max concurrent audits per process |
 | `CONTRASTCAP_VIEWPORT_WIDTH` | `1280` | Chromium viewport width |
 | `CONTRASTCAP_VIEWPORT_HEIGHT` | `800` | Chromium viewport height |
+| `CONTRASTCAP_BLOCK_PRIVATE` | unset | Set to `1` to block RFC1918 / loopback / CGNAT addresses (production hardening). See **Security**. |
+| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | unset | Set to `1` to skip the Chromium download in `postinstall` (offline / air-gapped installs). |
+| `PLAYWRIGHT_DOWNLOAD_HOST` | unset | Mirror host for Playwright's Chromium download. |
 
 ---
 
@@ -234,14 +237,25 @@ First-time publish is auto-detected (no existing version on npm) — the current
 
 ## Security
 
-- Scheme allowlist: `http:` and `https:` only. `file:`, `javascript:`, `data:`, `ftp:` etc. are rejected with a generic `Blocked URL scheme` error.
-- Cloud-metadata hostnames blocked: `169.254.169.254`, `metadata.google.internal`, `metadata.azure.com`, `0.0.0.0`.
-- IP-prefix denylist (DNS-resolved): IPv4 link-local (`169.254.`), IPv6 unique-local (`fd00:`), link-local (`fe80:`), unspecified (`::`). DNS-resolution failures fail closed.
-- Post-navigation re-check: after `page.goto` settles, `page.url()` is re-validated before any pixel sampling.
-- Generic error messages — no filesystem paths or stack traces are returned to MCP clients.
-- No file writes. Screenshots are in-memory buffers consumed by `sharp` and discarded.
+### Threat model
 
-Private / localhost IPs are **allowed** by design — the primary use case is auditing dev servers.
+`contrastcap` is an MCP server invoked by an LLM that may be acting on prompt-injected, attacker-controlled content. The dangerous tools are `check_page_contrast` and `check_element_contrast` — both accept a URL and load it in headless Chromium. A malicious URL could attempt to pivot to internal network resources (SSRF), exfiltrate page content via element text, or load adversarial schemes (`file:`, `javascript:`, `data:`).
+
+### Controls
+
+- **Scheme allowlist**: `http:` and `https:` only. `file:`, `javascript:`, `data:`, `ftp:`, etc. are rejected with a generic `Blocked URL scheme` error.
+- **Cloud-metadata blocklist** (always on): `169.254.169.254`, `metadata.google.internal`, `metadata.azure.com`, `0.0.0.0`.
+- **CIDR-classified IP blocking** (always on): IPv4 link-local (`169.254.0.0/16`), IPv6 link-local (`fe80::/10`), IPv6 unspecified (`::`), IPv4 multicast/reserved (`224.0.0.0/4`+), IPv6 multicast (`ff00::/8`). IPv4-mapped IPv6 addresses are unwrapped first so `::ffff:169.254.169.254` is recognized as link-local. DNS-resolution failures fail closed.
+- **Optional private-IP blocking**: set `CONTRASTCAP_BLOCK_PRIVATE=1` to also block RFC1918 (`10/8`, `172.16/12`, `192.168/16`), CGNAT (`100.64/10`), loopback (`127/8`, `::1`), and IPv6 ULA (`fc00::/7`). Off by default — the primary use case is auditing dev servers — but **strongly recommended** when running the server in a trusted internal network where the LLM should not be able to pivot to internal services via prompt injection.
+- **Post-navigation re-check**: after `page.goto` settles, `page.url()` is re-validated against the same SSRF policy. This catches `http://attacker.com/redirect` → `http://10.0.0.5/admin`.
+- **Selector hardening**: `check_element_contrast` rejects Playwright engine prefixes (`xpath=`, `text=`, `role=`, `internal:*`, `_react=`, `_vue=`, etc.) and chain operators (`>>`). Only plain CSS selectors are accepted, so a malicious selector cannot pivot to XPath / text-content matching to read arbitrary DOM text.
+- **Generic error messages** — no filesystem paths or stack traces are returned to MCP clients.
+- **No file writes.** Screenshots are in-memory buffers consumed by `sharp` and discarded.
+- **Hardened postinstall**: Playwright's CLI is resolved through Node's module resolver (`require.resolve`) rather than `$PATH`, so a shadowed `playwright` binary cannot hijack the install. Chromium download can be skipped (`PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1`) or mirrored (`PLAYWRIGHT_DOWNLOAD_HOST`). If Chromium is missing at runtime, the launcher emits an actionable error rather than a Playwright-internal stack trace.
+
+### Audit history
+
+A red/blue team audit covering the MCP tool surface, Playwright/browser launch, dependency posture, and publish pipeline was performed in 0.1.4 (see CHANGELOG). `pnpm audit` is clean (0 vulnerabilities across all dependencies).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icjia/contrastcap",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "MCP server for automated WCAG contrast auditing via pixel-level analysis — resolves axe-core 'needs review' items by sampling actual rendered pixels in headless Chromium",
   "type": "module",
   "main": "src/server.js",
@@ -10,10 +10,11 @@
   "scripts": {
     "start": "node src/server.js",
     "test": "node --test test/*.test.js",
-    "postinstall": "node -e \"try { require('child_process').execSync('playwright install chromium', { stdio: 'inherit' }) } catch (e) { console.error('[contrastcap] playwright install chromium failed:', e.message); process.exit(0) }\""
+    "postinstall": "node scripts/postinstall.mjs"
   },
   "files": [
     "src/",
+    "scripts/postinstall.mjs",
     "README.md"
   ],
   "engines": {

package/scripts/postinstall.mjs

@@ -0,0 +1,53 @@
+// Resolve Playwright's CLI through Node's module resolver (not $PATH) and
+// invoke it directly. Failure is reported but does not abort the parent
+// install — Chromium download can fail for legitimate reasons (offline CI,
+// air-gapped network, restricted egress). Users who hit that get a clear
+// error pointing to the manual fix instead of a silent broken install at
+// audit time.
+//
+// Skip download entirely:
+//   PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
+// Use a private mirror:
+//   PLAYWRIGHT_DOWNLOAD_HOST=https://mirror.example.com
+
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+
+if (process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD === '1') {
+  console.error('[contrastcap] PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 — skipping Chromium install.');
+  process.exit(0);
+}
+
+const require = createRequire(import.meta.url);
+
+let cliPath;
+try {
+  cliPath = require.resolve('playwright/cli.js');
+} catch {
+  try {
+    cliPath = require.resolve('playwright-core/cli.js');
+  } catch (err) {
+    console.error('[contrastcap] could not resolve Playwright CLI:', err.message);
+    console.error('[contrastcap] run `npx playwright install chromium` manually before first audit.');
+    process.exit(0);
+  }
+}
+
+const result = spawnSync(process.execPath, [cliPath, 'install', 'chromium'], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+if (result.error) {
+  console.error('[contrastcap] playwright install chromium failed to spawn:', result.error.message);
+  console.error('[contrastcap] run `npx playwright install chromium` manually before first audit.');
+  process.exit(0);
+}
+
+if (result.status !== 0) {
+  console.error(`[contrastcap] playwright install chromium exited with status ${result.status}.`);
+  console.error('[contrastcap] run `npx playwright install chromium` manually before first audit.');
+  // Do not propagate non-zero — install can complete; runtime will surface a
+  // helpful error if Chromium is genuinely missing.
+  process.exit(0);
+}

package/src/browser.js

@@ -26,6 +26,12 @@ export async function getBrowser() {
     return b;
   }).catch((err) => {
     _launching = null;
+    if (/Executable doesn't exist|browserType\.launch/i.test(err.message || '')) {
+      throw new Error(
+        "Chromium is not installed. Run `npx playwright install chromium` " +
+        "to download it (~200 MB), or set PLAYWRIGHT_DOWNLOAD_HOST to a mirror."
+      );
+    }
     throw err;
   });
 

package/src/cli.js

@@ -3,6 +3,7 @@
 import { program } from 'commander';
 import { readFileSync } from 'fs';
 import { execFile } from 'child_process';
+import { createRequire } from 'module';
 import { setVerbosity, CONFIG } from './config.js';
 import { closeBrowser } from './browser.js';
 import { checkPageContrast } from './tools/checkPageContrast.js';
@@ -10,8 +11,17 @@ import { checkElementContrast } from './tools/checkElementContrast.js';
 import { getContrastSummary } from './tools/getContrastSummary.js';
 import { sanitizeError } from './utils/sanitizeError.js';
 
+const require = createRequire(import.meta.url);
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url)));
 
+function readPkgVersion(specifier) {
+  try {
+    return JSON.parse(readFileSync(require.resolve(`${specifier}/package.json`), 'utf8')).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
 program
   .name('contrastcap')
   .description('WCAG contrast auditor — pixel-level resolution of axe-core "needs review" items')
@@ -74,14 +84,8 @@ program
   .command('status')
   .description('Show version info')
   .action(async () => {
-    let axeVersion = 'unknown';
-    let playwrightVersion = 'unknown';
-    try {
-      axeVersion = JSON.parse(readFileSync(new URL('../node_modules/axe-core/package.json', import.meta.url))).version;
-    } catch { /* ignore */ }
-    try {
-      playwrightVersion = JSON.parse(readFileSync(new URL('../node_modules/playwright/package.json', import.meta.url))).version;
-    } catch { /* ignore */ }
+    const axeVersion = readPkgVersion('axe-core');
+    const playwrightVersion = readPkgVersion('playwright');
 
     let latest = 'unknown';
     try {

package/src/config.js

@@ -35,22 +35,21 @@ export const CONFIG = {
 
   USER_AGENT: 'contrastcap-mcp/0.1 (WCAG contrast auditor)',
 
-  // SSRF denylist — mirrors lightcap.
+  // SSRF policy.
+  // Always-blocked hostnames (cloud metadata + 0.0.0.0 sentinel).
   BLOCKED_HOSTNAMES: [
     '169.254.169.254',
     'metadata.google.internal',
     'metadata.azure.com',
     '0.0.0.0',
   ],
-  BLOCKED_IP_PREFIXES: [
-    '169.254.',                // IPv4 link-local (AWS IMDS)
-    'fd00:',                   // IPv6 unique-local
-    'fe80:',                   // IPv6 link-local
-    '::',                      // IPv6 unspecified/loopback-equivalent
-  ],
-  LOCALHOST_HOSTS: [
-    'localhost', '127.0.0.1', '::1', '[::1]',
-  ],
+  // Network-class blocking is handled by CIDR classification in
+  // src/utils/urlValidate.js — link-local (incl. cloud metadata),
+  // unspecified, multicast, and reserved ranges are *always* blocked.
+  // Private/loopback/CGNAT are allowed by default so the dev-server
+  // workflow keeps working, and blocked when this flag is on.
+  // Read at call time so the env flag can be flipped per-process.
+  get BLOCK_PRIVATE_IPS() { return process.env.CONTRASTCAP_BLOCK_PRIVATE === '1'; },
 };
 
 // ─── Logging ──────────────────────────────────────────────────────

package/src/server.js

@@ -2,9 +2,20 @@
 
 import { readFileSync } from 'fs';
 import { execFile } from 'child_process';
+import { createRequire } from 'module';
 import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
 import * as z from 'zod/v4';
 
+const require = createRequire(import.meta.url);
+
+function readPkgVersion(specifier) {
+  try {
+    return JSON.parse(readFileSync(require.resolve(`${specifier}/package.json`), 'utf8')).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
 import { CONFIG, log, setVerbosity } from './config.js';
 import { closeBrowser } from './browser.js';
 import { sanitizeError } from './utils/sanitizeError.js';
@@ -20,14 +31,8 @@ if (process.argv.includes('--quiet')) setVerbosity('quiet');
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url)));
 const serverVersion = pkg.version;
 
-let axeVersion = 'unknown';
-let playwrightVersion = 'unknown';
-try {
-  axeVersion = JSON.parse(readFileSync(new URL('../node_modules/axe-core/package.json', import.meta.url))).version;
-} catch { /* ignore */ }
-try {
-  playwrightVersion = JSON.parse(readFileSync(new URL('../node_modules/playwright/package.json', import.meta.url))).version;
-} catch { /* ignore */ }
+const axeVersion = readPkgVersion('axe-core');
+const playwrightVersion = readPkgVersion('playwright');
 
 let _latestVersion = null;
 const _latestPromise = new Promise((resolve) => {

package/src/tools/checkElementContrast.js

@@ -1,5 +1,6 @@
 import { CONFIG } from '../config.js';
 import { validateUrl } from '../utils/urlValidate.js';
+import { validateSelector } from '../utils/selectorValidate.js';
 import { withPage } from '../browser.js';
 import { sampleBackgroundColor } from '../engine/pixelSampler.js';
 import {
@@ -20,10 +21,7 @@ function rgbStringToHex(rgbStr) {
 
 export async function checkElementContrast(params) {
   const level = params.level || CONFIG.DEFAULT_LEVEL;
-  const selector = params.selector;
-  if (typeof selector !== 'string' || selector.length === 0 || selector.length > CONFIG.SELECTOR_MAX_LEN) {
-    throw new Error('Invalid selector');
-  }
+  const selector = validateSelector(params.selector);
 
   const validated = await validateUrl(params.url);
 

package/src/utils/selectorValidate.js

@@ -0,0 +1,19 @@
+import { CONFIG } from '../config.js';
+
+// Reject Playwright engine-prefixed selectors (xpath=, text=, id=, css=, role=,
+// nth=, visible=, internal:*, _react=, _vue=) and chain operators (`>>` / `>>>`).
+// We accept only plain CSS selectors so a malicious caller cannot pivot into
+// XPath / text-content matching to exfiltrate page content via element text.
+const ENGINE_PREFIX = /^\s*(xpath|text|id|css|role|nth|visible|internal:[\w-]+|_react|_vue|data-testid|alt|placeholder|title|label)\s*=/i;
+const CHAIN_OPERATOR = />>/;
+
+export function validateSelector(selector) {
+  if (typeof selector !== 'string' || selector.length === 0
+      || selector.length > CONFIG.SELECTOR_MAX_LEN) {
+    throw new Error('Invalid selector');
+  }
+  if (ENGINE_PREFIX.test(selector) || CHAIN_OPERATOR.test(selector)) {
+    throw new Error('Invalid selector');
+  }
+  return selector;
+}

package/src/utils/urlValidate.js

@@ -1,12 +1,79 @@
 import { lookup } from 'dns/promises';
+import { isIP } from 'net';
 import { CONFIG } from '../config.js';
 
-async function isBlockedIp(hostname) {
-  if (CONFIG.LOCALHOST_HOSTS.includes(hostname)) return false;
+// Classify an IP address into a network category. Returns one of:
+//   'loopback'   – 127.0.0.0/8, ::1
+//   'private'    – RFC1918 (10/8, 172.16/12, 192.168/16), IPv6 ULA (fc00::/7)
+//   'cgnat'      – 100.64.0.0/10
+//   'link-local' – 169.254.0.0/16 (incl. cloud metadata), fe80::/10
+//   'unspecified'– 0.0.0.0, ::
+//   'reserved'   – multicast / class E / other non-routable
+//   'public'     – everything else
+//   'invalid'    – not parseable
+function classifyIp(address) {
+  if (typeof address !== 'string') return 'invalid';
+  // Unwrap IPv4-mapped IPv6 (e.g. ::ffff:10.0.0.1) so v4 rules apply.
+  const ip = /^::ffff:/i.test(address) ? address.slice(7) : address;
+  const v = isIP(ip);
+
+  if (v === 4) {
+    const parts = ip.split('.').map(Number);
+    if (parts.length !== 4 || parts.some(n => !Number.isInteger(n) || n < 0 || n > 255)) {
+      return 'invalid';
+    }
+    const [a, b] = parts;
+    if (a === 0) return 'unspecified';
+    if (a === 127) return 'loopback';
+    if (a === 169 && b === 254) return 'link-local';
+    if (a === 10) return 'private';
+    if (a === 172 && b >= 16 && b <= 31) return 'private';
+    if (a === 192 && b === 168) return 'private';
+    if (a === 100 && b >= 64 && b <= 127) return 'cgnat';
+    if (a >= 224) return 'reserved'; // multicast (224-239), class E (240+), broadcast (255)
+    return 'public';
+  }
+
+  if (v === 6) {
+    const lower = ip.toLowerCase();
+    if (lower === '::') return 'unspecified';
+    if (lower === '::1') return 'loopback';
+    if (/^fe[89ab][0-9a-f]?:/.test(lower)) return 'link-local';
+    if (/^f[cd][0-9a-f]{2}:/.test(lower)) return 'private'; // fc00::/7 ULA
+    if (lower.startsWith('ff')) return 'reserved';          // multicast
+    return 'public';
+  }
+
+  return 'invalid';
+}
+
+function isAllowedClass(category) {
+  switch (category) {
+    case 'public':
+      return true;
+    case 'loopback':
+    case 'private':
+    case 'cgnat':
+      return !CONFIG.BLOCK_PRIVATE_IPS;
+    // 'link-local' (cloud metadata), 'unspecified', 'reserved', 'invalid' → always blocked
+    default:
+      return false;
+  }
+}
+
+async function isBlockedHost(hostname) {
+  if (!hostname) return true;
+  // If the hostname is already a literal IP, classify directly without DNS.
+  if (isIP(hostname)) return !isAllowedClass(classifyIp(hostname));
+  // Strip surrounding brackets from IPv6 literals (URL hostnames keep them).
+  const stripped = hostname.startsWith('[') && hostname.endsWith(']')
+    ? hostname.slice(1, -1)
+    : hostname;
+  if (isIP(stripped)) return !isAllowedClass(classifyIp(stripped));
+
   try {
     const { address } = await lookup(hostname);
-    const normalized = address.startsWith('::ffff:') ? address.slice(7) : address;
-    return CONFIG.BLOCKED_IP_PREFIXES.some(p => normalized.startsWith(p));
+    return !isAllowedClass(classifyIp(address));
   } catch {
     return true; // DNS failure → fail closed
   }
@@ -26,10 +93,10 @@ export async function validateUrl(url) {
   if (CONFIG.BLOCKED_HOSTNAMES.includes(parsed.hostname)) {
     throw new Error('Blocked URL');
   }
-  if (await isBlockedIp(parsed.hostname)) {
+  if (await isBlockedHost(parsed.hostname)) {
     throw new Error('Blocked URL');
   }
   return parsed.href;
 }
 
-export const _test = { isBlockedIp };
+export const _test = { isBlockedHost, classifyIp };