@layerporter/image-optimizer-mcp 0.1.0

package/src/image-core/page-analysis.js

@@ -0,0 +1,204 @@
+const DEFAULTS = Object.freeze({
+  oversizeRatioWarn: 1.5,
+  oversizeRatioHigh: 2,
+  minRenderedPixels: 16,
+});
+
+function finitePositive(value) {
+  return Number.isFinite(value) && value > 0;
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function normalizeUrl(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function confidenceFromEvidence(evidenceCount, max = 6) {
+  return Number(clamp(evidenceCount / max, 0.25, 1).toFixed(2));
+}
+
+export function analyzeImageUsage(image, options = {}) {
+  if (!image || typeof image !== 'object') throw new TypeError('image facts are required');
+
+  const cfg = { ...DEFAULTS, ...options };
+  const intrinsicWidth = Number(image.intrinsicWidth ?? 0);
+  const intrinsicHeight = Number(image.intrinsicHeight ?? 0);
+  const renderedWidth = Number(image.renderedWidth ?? 0);
+  const renderedHeight = Number(image.renderedHeight ?? 0);
+  const dpr = finitePositive(Number(image.devicePixelRatio)) ? Number(image.devicePixelRatio) : 1;
+
+  const hasDimensions = [intrinsicWidth, intrinsicHeight, renderedWidth, renderedHeight].every(finitePositive);
+  const requiredWidth = hasDimensions ? renderedWidth * dpr : null;
+  const requiredHeight = hasDimensions ? renderedHeight * dpr : null;
+  const widthRatio = hasDimensions ? intrinsicWidth / requiredWidth : null;
+  const heightRatio = hasDimensions ? intrinsicHeight / requiredHeight : null;
+  const oversizeRatio = hasDimensions ? Number(Math.max(widthRatio, heightRatio).toFixed(2)) : null;
+
+  const src = normalizeUrl(image.currentSrc ?? image.src);
+  const format = typeof image.format === 'string' ? image.format.toLowerCase() : null;
+  const bytes = Number.isFinite(image.bytes) && image.bytes >= 0 ? image.bytes : null;
+  const hasSrcset = typeof image.srcset === 'string' && image.srcset.trim().length > 0;
+  const hasSizes = typeof image.sizes === 'string' && image.sizes.trim().length > 0;
+  const loading = typeof image.loading === 'string' ? image.loading.toLowerCase() : null;
+  const fetchPriority = typeof image.fetchPriority === 'string' ? image.fetchPriority.toLowerCase() : null;
+  const widthAttr = Number(image.widthAttr ?? 0);
+  const heightAttr = Number(image.heightAttr ?? 0);
+  const hasDimensionAttrs = finitePositive(widthAttr) && finitePositive(heightAttr);
+
+  const evidence = [];
+  if (src) evidence.push({ type: 'url', value: src });
+  if (hasDimensions) evidence.push({ type: 'dimensions', intrinsic: [intrinsicWidth, intrinsicHeight], rendered: [renderedWidth, renderedHeight], dpr });
+  if (bytes !== null) evidence.push({ type: 'bytes', value: bytes });
+  if (format) evidence.push({ type: 'format', value: format });
+  if (image.lcp === true) evidence.push({ type: 'lcp', value: 'confirmed' });
+  else if (image.hero === true) evidence.push({ type: 'hero', value: 'page-marked' });
+
+  let role = 'content';
+  let roleConfidence = 0.5;
+  if (image.lcp === true) {
+    role = 'lcp';
+    roleConfidence = 1;
+  } else if (image.hero === true) {
+    role = 'hero_candidate';
+    roleConfidence = 0.75;
+  } else if (image.decorative === true) {
+    role = 'decorative';
+    roleConfidence = 0.9;
+  }
+
+  const findings = [];
+  const findingBase = {
+    category: 'image',
+    imageUrl: src,
+    evidence,
+    confidence: confidenceFromEvidence(evidence.length),
+  };
+
+  if (oversizeRatio !== null && oversizeRatio >= cfg.oversizeRatioWarn) {
+    findings.push({
+      ...findingBase,
+      id: 'oversized_image',
+      severity: oversizeRatio >= cfg.oversizeRatioHigh ? 'high' : 'medium',
+      impact: oversizeRatio >= cfg.oversizeRatioHigh ? 'high' : 'medium',
+      currentState: { intrinsicWidth, intrinsicHeight, renderedWidth, renderedHeight, dpr, oversizeRatio },
+      expectedState: { maxWidth: Math.ceil(requiredWidth), maxHeight: Math.ceil(requiredHeight) },
+      risk: 'low',
+      autoFixability: 'SAFE',
+      suggestedFix: 'resize_or_generate_responsive_variant',
+      verificationMethod: 'dimensions_and_bytes_before_after',
+    });
+  }
+
+  if (!hasSrcset && hasDimensions && renderedWidth >= cfg.minRenderedPixels) {
+    findings.push({
+      ...findingBase,
+      id: 'missing_srcset',
+      severity: oversizeRatio !== null && oversizeRatio >= cfg.oversizeRatioWarn ? 'medium' : 'low',
+      impact: 'medium',
+      currentState: { srcset: null, sizes: hasSizes ? image.sizes : null },
+      expectedState: { responsiveVariants: true },
+      risk: 'low',
+      autoFixability: 'SAFE',
+      suggestedFix: 'generate_responsive_variants',
+      verificationMethod: 'responsive_markup_and_network_bytes',
+    });
+  }
+
+  if (hasSrcset && !hasSizes) {
+    findings.push({
+      ...findingBase,
+      id: 'missing_sizes',
+      severity: 'low',
+      impact: 'medium',
+      currentState: { srcset: image.srcset, sizes: null },
+      expectedState: { sizes: 'context_derived' },
+      risk: 'review',
+      autoFixability: 'REVIEW',
+      suggestedFix: 'derive_sizes_from_layout_context',
+      verificationMethod: 'viewport_candidate_selection',
+    });
+  }
+
+  if (!hasDimensionAttrs && hasDimensions) {
+    findings.push({
+      ...findingBase,
+      id: 'missing_dimension_attributes',
+      severity: 'low',
+      impact: 'medium',
+      currentState: { widthAttr: widthAttr || null, heightAttr: heightAttr || null },
+      expectedState: { width: intrinsicWidth, height: intrinsicHeight },
+      risk: 'low',
+      autoFixability: 'SAFE',
+      suggestedFix: 'add_width_height_attributes',
+      verificationMethod: 'dom_attributes_and_cls_regression',
+    });
+  }
+
+  if (role === 'lcp' && loading === 'lazy') {
+    findings.push({
+      ...findingBase,
+      id: 'lcp_lazy_loaded',
+      severity: 'high',
+      impact: 'high',
+      currentState: { loading, fetchPriority },
+      expectedState: { loading: 'eager_or_default', fetchPriority: 'high_when_confirmed' },
+      risk: 'low',
+      autoFixability: 'SAFE',
+      suggestedFix: 'remove_lazy_from_confirmed_lcp',
+      verificationMethod: 'lcp_resource_timing_before_after',
+    });
+  }
+
+  if (role === 'lcp' && fetchPriority !== 'high') {
+    findings.push({
+      ...findingBase,
+      id: 'lcp_missing_fetchpriority',
+      severity: 'medium',
+      impact: 'medium',
+      currentState: { fetchPriority: fetchPriority || null },
+      expectedState: { fetchPriority: 'high' },
+      risk: 'low',
+      autoFixability: 'SAFE',
+      suggestedFix: 'set_fetchpriority_high',
+      verificationMethod: 'resource_priority_and_lcp_before_after',
+    });
+  }
+
+  return {
+    src,
+    format,
+    bytes,
+    intrinsic: hasDimensions ? { width: intrinsicWidth, height: intrinsicHeight } : null,
+    rendered: hasDimensions ? { width: renderedWidth, height: renderedHeight, dpr } : null,
+    required: hasDimensions ? { width: Math.ceil(requiredWidth), height: Math.ceil(requiredHeight) } : null,
+    oversizeRatio,
+    responsive: { hasSrcset, hasSizes, srcset: hasSrcset ? image.srcset : null, sizes: hasSizes ? image.sizes : null },
+    loading: { loading, fetchPriority },
+    attributes: { width: widthAttr || null, height: heightAttr || null, complete: hasDimensionAttrs },
+    role: { value: role, confidence: roleConfidence },
+    findings,
+  };
+}
+
+export function analyzePageImages(snapshot, options = {}) {
+  if (!snapshot || typeof snapshot !== 'object') throw new TypeError('page snapshot is required');
+  if (!Array.isArray(snapshot.images)) throw new TypeError('page snapshot.images must be an array');
+
+  const pageUrl = normalizeUrl(snapshot.pageUrl);
+  const images = snapshot.images.map((image, index) => ({ index, ...analyzeImageUsage(image, options) }));
+  const findings = images.flatMap((item) => item.findings.map((finding) => ({ ...finding, pageUrl, imageIndex: item.index })));
+
+  const priority = { high: 3, medium: 2, low: 1 };
+  findings.sort((a, b) => (priority[b.severity] ?? 0) - (priority[a.severity] ?? 0));
+
+  return {
+    pageUrl,
+    imageCount: images.length,
+    findingsCount: findings.length,
+    images,
+    findings,
+  };
+}

package/src/image-core/policy.js

@@ -0,0 +1,49 @@
+export const ALLOWED_FORMATS = new Set(['jpeg', 'png', 'webp', 'avif']);
+
+export const DEFAULT_POLICY = Object.freeze({
+  format: 'auto',
+  quality: 82,
+  avifQuality: 50,
+  effort: 4,
+  withoutEnlargement: true,
+  preserveAlpha: true,
+  preserveOrientation: true,
+  neverIncreaseBytes: true,
+  maxWidth: 8192,
+  maxHeight: 8192,
+  maxPixels: 40_000_000,
+});
+
+export function validatePolicy(policy = {}) {
+  const merged = { ...DEFAULT_POLICY, ...policy };
+
+  if (!['auto', ...ALLOWED_FORMATS].includes(merged.format)) {
+    throw new TypeError(`Unsupported output format: ${merged.format}`);
+  }
+
+  if (!Number.isInteger(merged.quality) || merged.quality < 1 || merged.quality > 100) {
+    throw new TypeError('quality must be an integer between 1 and 100');
+  }
+
+  if (!Number.isInteger(merged.avifQuality) || merged.avifQuality < 1 || merged.avifQuality > 100) {
+    throw new TypeError('avifQuality must be an integer between 1 and 100');
+  }
+
+  if (!Number.isInteger(merged.effort) || merged.effort < 0 || merged.effort > 9) {
+    throw new TypeError('effort must be an integer between 0 and 9');
+  }
+
+  return merged;
+}
+
+export function chooseOutputFormat(metadata, policy) {
+  if (policy.format !== 'auto') return policy.format;
+
+  if (metadata.hasAlpha) {
+    return metadata.format === 'png' ? 'webp' : metadata.format || 'webp';
+  }
+
+  if (metadata.format === 'jpeg' || metadata.format === 'png') return 'webp';
+  if (metadata.format === 'webp' || metadata.format === 'avif') return metadata.format;
+  return 'webp';
+}

package/src/image-core/safe-fix.js

@@ -0,0 +1,91 @@
+import { inspectImage, optimizeImage } from './index.js';
+
+const SAFE_IMAGE_RULES = new Set(['oversized_image', 'missing_image_dimensions', 'missing_srcset']);
+const BYTE_TRANSFORM_RULES = new Set(['oversized_image']);
+
+function cloneBuffer(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length === 0) throw new TypeError('buffer must be a non-empty Buffer');
+  return Buffer.from(buffer);
+}
+
+export function buildSafeImageFixPlan({ finding, image }) {
+  if (!finding || !SAFE_IMAGE_RULES.has(finding.ruleId)) {
+    return { status: 'REVIEW_REQUIRED', reason: 'finding is outside the safe image allowlist' };
+  }
+  if (!BYTE_TRANSFORM_RULES.has(finding.ruleId)) {
+    return {
+      status: 'REVIEW_REQUIRED',
+      reason: 'this finding requires a markup patch; byte optimization alone cannot resolve it',
+    };
+  }
+  if (finding.confidence !== 'high') {
+    return { status: 'REVIEW_REQUIRED', reason: 'high confidence is required for safe image fix' };
+  }
+  const renderedWidth = Number(image?.renderedWidth || 0);
+  const renderedHeight = Number(image?.renderedHeight || 0);
+  const intrinsicWidth = Number(image?.intrinsicWidth || 0);
+  const intrinsicHeight = Number(image?.intrinsicHeight || 0);
+  if (!renderedWidth || !renderedHeight || !intrinsicWidth || !intrinsicHeight) {
+    return { status: 'REVIEW_REQUIRED', reason: 'complete rendered and intrinsic dimensions are required' };
+  }
+  if (intrinsicWidth <= renderedWidth * 2 && intrinsicHeight <= renderedHeight * 2) {
+    return { status: 'REVIEW_REQUIRED', reason: 'oversize threshold is not independently confirmed' };
+  }
+  return {
+    status: 'READY',
+    ruleId: finding.ruleId,
+    target: {
+      width: Math.min(intrinsicWidth, Math.ceil(renderedWidth)),
+      height: Math.min(intrinsicHeight, Math.ceil(renderedHeight)),
+    },
+    policy: {
+      withoutEnlargement: true,
+      preserveAlpha: true,
+      neverIncreaseBytes: true,
+    },
+  };
+}
+
+export async function prepareSafeImageFix({ buffer, plan, policy = {} }) {
+  if (!plan || plan.status !== 'READY') throw new TypeError('READY safe image fix plan required');
+  const originalBuffer = cloneBuffer(buffer);
+  const before = await inspectImage(originalBuffer, { policy: { ...plan.policy, ...policy } });
+  const optimized = await optimizeImage(originalBuffer, {
+    target: plan.target,
+    policy: { ...plan.policy, ...policy },
+  });
+
+  if (optimized.status !== 'ACCEPT' || !Buffer.isBuffer(optimized.buffer)) {
+    return {
+      status: 'REJECT',
+      reason: optimized.reason || 'candidate failed optimization guards',
+      before,
+      after: optimized.output || null,
+      savingsBytes: optimized.savingsBytes ?? 0,
+      candidateBuffer: null,
+    };
+  }
+
+  const candidateBuffer = Buffer.from(optimized.buffer);
+  const after = await inspectImage(candidateBuffer, { policy: { ...plan.policy, ...policy } });
+  const savingsBytes = before.bytes - after.bytes;
+  const noUpscale = after.width <= before.width && after.height <= before.height;
+  const alphaPreserved = !before.hasAlpha || after.hasAlpha;
+  const smaller = savingsBytes > 0;
+  const targetSatisfied = after.width <= plan.target.width && after.height <= plan.target.height;
+  const originalUnchanged = buffer.equals(originalBuffer);
+  const guardsPass = noUpscale && alphaPreserved && smaller && targetSatisfied && originalUnchanged;
+
+  return {
+    status: guardsPass ? 'PREVIEW_READY' : 'REJECT',
+    before,
+    after,
+    savingsBytes,
+    savingsPercent: Number(((savingsBytes / before.bytes) * 100).toFixed(2)),
+    checks: { noUpscale, alphaPreserved, smaller, targetSatisfied, originalUnchanged },
+    candidateBuffer: guardsPass ? candidateBuffer : null,
+  };
+}
+
+export const SAFE_IMAGE_FIX_RULES = Object.freeze([...SAFE_IMAGE_RULES]);
+export const BYTE_TRANSFORM_SAFE_IMAGE_RULES = Object.freeze([...BYTE_TRANSFORM_RULES]);

package/src/secure-fetch.js

@@ -0,0 +1,193 @@
+import dns from 'node:dns';
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+
+const BLOCKED_V4 = new net.BlockList();
+for (const [network, prefix] of [
+  ['0.0.0.0', 8],
+  ['10.0.0.0', 8],
+  ['100.64.0.0', 10],
+  ['127.0.0.0', 8],
+  ['169.254.0.0', 16],
+  ['172.16.0.0', 12],
+  ['192.0.0.0', 24],
+  ['192.0.2.0', 24],
+  ['192.168.0.0', 16],
+  ['198.18.0.0', 15],
+  ['198.51.100.0', 24],
+  ['203.0.113.0', 24],
+  ['224.0.0.0', 4],
+  ['240.0.0.0', 4],
+]) BLOCKED_V4.addSubnet(network, prefix, 'ipv4');
+
+const BLOCKED_V6 = new net.BlockList();
+for (const [network, prefix] of [
+  ['::', 128],
+  ['::1', 128],
+  ['100::', 64],
+  ['2001:db8::', 32],
+  ['fc00::', 7],
+  ['fe80::', 10],
+  ['ff00::', 8],
+]) BLOCKED_V6.addSubnet(network, prefix, 'ipv6');
+
+function securityError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function bareHostname(value) {
+  return value.replace(/^\[|\]$/g, '').replace(/\.$/, '').toLowerCase();
+}
+
+export function isBlockedAddress(address) {
+  const family = net.isIP(address);
+  if (!family) return true;
+  if (family === 4) return BLOCKED_V4.check(address, 'ipv4');
+
+  const lower = address.toLowerCase();
+  if (lower.startsWith('::ffff:')) {
+    const mapped = lower.slice('::ffff:'.length);
+    if (net.isIP(mapped) === 4) return BLOCKED_V4.check(mapped, 'ipv4');
+  }
+  return BLOCKED_V6.check(address, 'ipv6');
+}
+
+export function validateRemoteUrl(input) {
+  let url;
+  try {
+    url = input instanceof URL ? new URL(input.href) : new URL(String(input));
+  } catch {
+    throw securityError('INVALID_URL', 'invalid URL');
+  }
+
+  if (!['http:', 'https:'].includes(url.protocol)) throw securityError('UNSAFE_SCHEME', 'only http and https URLs are allowed');
+  if (url.username || url.password) throw securityError('URL_CREDENTIALS_BLOCKED', 'credentials in URLs are not allowed');
+
+  const hostname = bareHostname(url.hostname);
+  if (!hostname) throw securityError('INVALID_HOST', 'URL hostname is required');
+  if (hostname === 'localhost' || hostname.endsWith('.localhost')) throw securityError('PRIVATE_HOST_BLOCKED', 'localhost is not allowed');
+  if (net.isIP(hostname) && isBlockedAddress(hostname)) throw securityError('PRIVATE_IP_BLOCKED', 'private or non-routable IP is not allowed');
+
+  return url;
+}
+
+export function createSafeLookup(lookupFn = dns.lookup) {
+  return function safeLookup(hostname, options, callback) {
+    lookupFn(hostname, { all: true, verbatim: true }, (error, addresses) => {
+      if (error) return callback(error);
+      if (!Array.isArray(addresses) || addresses.length === 0) return callback(securityError('DNS_EMPTY', 'hostname did not resolve'));
+      if (addresses.some((entry) => isBlockedAddress(entry.address))) {
+        return callback(securityError('PRIVATE_DNS_BLOCKED', 'hostname resolved to a private or non-routable IP'));
+      }
+
+      const requestedFamily = typeof options === 'number' ? options : options?.family;
+      const candidates = requestedFamily === 4 || requestedFamily === 6
+        ? addresses.filter((entry) => entry.family === requestedFamily)
+        : addresses;
+      if (candidates.length === 0) return callback(securityError('DNS_FAMILY_MISMATCH', 'hostname has no address for requested family'));
+
+      if (typeof options === 'object' && options?.all) return callback(null, candidates);
+      return callback(null, candidates[0].address, candidates[0].family);
+    });
+  };
+}
+
+export async function requestOnce(url, options = {}) {
+  const safeUrl = validateRemoteUrl(url);
+  const maxBytes = options.maxBytes ?? 2 * 1024 * 1024;
+  const timeoutMs = options.timeoutMs ?? 8000;
+  const lookup = options.lookup ?? createSafeLookup();
+  const hostname = bareHostname(safeUrl.hostname);
+  const transport = safeUrl.protocol === 'https:' ? https : http;
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    };
+
+    const request = transport.request({
+      protocol: safeUrl.protocol,
+      hostname,
+      port: safeUrl.port || undefined,
+      path: `${safeUrl.pathname}${safeUrl.search}`,
+      method: 'GET',
+      lookup,
+      agent: false,
+      servername: net.isIP(hostname) ? undefined : hostname,
+      headers: {
+        'user-agent': 'LayerPorter-Image-Optimizer/0.1 (+https://layerporter.com/)',
+        accept: options.accept ?? '*/*',
+        'accept-encoding': 'identity',
+        connection: 'close',
+      },
+    }, (response) => {
+      const status = response.statusCode ?? 0;
+      const headers = response.headers;
+      const location = headers.location;
+
+      if ([301, 302, 303, 307, 308].includes(status) && location) {
+        response.resume();
+        if (!settled) {
+          settled = true;
+          resolve({ status, headers, body: Buffer.alloc(0), location });
+        }
+        return;
+      }
+
+      const contentLength = Number(headers['content-length'] ?? 0);
+      if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+        response.destroy();
+        return fail(securityError('RESPONSE_TOO_LARGE', 'response exceeds byte limit'));
+      }
+
+      const chunks = [];
+      let bytes = 0;
+      response.on('data', (chunk) => {
+        bytes += chunk.length;
+        if (bytes > maxBytes) {
+          response.destroy();
+          fail(securityError('RESPONSE_TOO_LARGE', 'response exceeds byte limit'));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on('error', fail);
+      response.on('end', () => {
+        if (settled) return;
+        settled = true;
+        resolve({ status, headers, body: Buffer.concat(chunks), location: null });
+      });
+    });
+
+    request.setTimeout(timeoutMs, () => request.destroy(securityError('REQUEST_TIMEOUT', 'request timed out')));
+    request.on('error', fail);
+    request.end();
+  });
+}
+
+export async function secureFetch(input, options = {}) {
+  const maxRedirects = Math.max(0, Math.min(options.maxRedirects ?? 3, 5));
+  const requestOnceImpl = options.requestOnceImpl ?? requestOnce;
+  let current = validateRemoteUrl(input);
+  const redirects = [];
+
+  for (let hop = 0; hop <= maxRedirects; hop += 1) {
+    const response = await requestOnceImpl(current, options);
+    if ([301, 302, 303, 307, 308].includes(response.status) && response.location) {
+      if (hop >= maxRedirects) throw securityError('TOO_MANY_REDIRECTS', 'redirect limit reached');
+      const next = validateRemoteUrl(new URL(response.location, current));
+      redirects.push({ from: current.href, to: next.href, status: response.status });
+      current = next;
+      continue;
+    }
+    return { ...response, url: current.href, redirects };
+  }
+
+  throw securityError('TOO_MANY_REDIRECTS', 'redirect limit reached');
+}