@aexol/spectral 0.9.42 → 0.9.43

package/dist/extensions/seo/utils/url-safety.js

@@ -0,0 +1,200 @@
+/**
+ * URL validation and SSRF protection.
+ *
+ * Ported from the Python `url_safety.py` in claude-seo. Blocks requests to
+ * private/internal IP ranges to prevent server-side request forgery.
+ */
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { createHash } from "node:crypto";
+export class UrlSafetyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UrlSafetyError";
+    }
+}
+/** Private/loopback IPv4 CIDR prefixes. */
+const PRIVATE_IPV4_PREFIXES = [
+    "10.",
+    "172.16.", "172.17.", "172.18.", "172.19.", "172.20.", "172.21.", "172.22.", "172.23.", "172.24.", "172.25.", "172.26.", "172.27.", "172.28.", "172.29.", "172.30.", "172.31.",
+    "192.168.",
+    "169.254.",
+    "127.",
+    "0.",
+    "100.64.", "100.65.", "100.66.", "100.67.", "100.68.", "100.69.", "100.70.", "100.71.", "100.72.", "100.73.", "100.74.", "100.75.", "100.76.", "100.77.", "100.78.", "100.79.", "100.80.", "100.81.", "100.82.", "100.83.", "100.84.", "100.85.", "100.86.", "100.87.", "100.88.", "100.89.", "100.90.", "100.91.", "100.92.", "100.93.", "100.94.", "100.95.", "100.96.", "100.97.", "100.98.", "100.99.", "100.100.", "100.101.", "100.102.", "100.103.", "100.104.", "100.105.", "100.106.", "100.107.", "100.108.", "100.109.", "100.110.", "100.111.", "100.112.", "100.113.", "100.114.", "100.115.", "100.116.", "100.117.", "100.118.", "100.119.", "100.120.", "100.121.", "100.122.", "100.123.", "100.124.", "100.125.", "100.126.", "100.127.",
+];
+/** Blocked hostnames that resolve to metadata endpoints or local services. */
+const BLOCKED_HOSTNAMES = new Set([
+    "localhost",
+    "metadata.google.internal",
+    "metadata",
+    "169.254.169.254",
+    "fd00.local",
+    "metadata.aws.internal",
+]);
+function isPrivateIPv4(ip) {
+    for (const prefix of PRIVATE_IPV4_PREFIXES) {
+        if (ip.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+function isPrivateIPv6(ip) {
+    const lower = ip.toLowerCase();
+    return (lower === "::1" ||
+        lower.startsWith("fe80:") ||
+        lower.startsWith("fc00:") ||
+        lower.startsWith("fd00:") ||
+        lower.startsWith("fd01:") ||
+        lower.startsWith("::ffff:") && isPrivateIPv4(lower.replace("::ffff:", "")));
+}
+function isPrivateIp(ip) {
+    const family = isIP(ip);
+    if (family === 4)
+        return isPrivateIPv4(ip);
+    if (family === 6)
+        return isPrivateIPv6(ip);
+    return false;
+}
+/**
+ * Validate a URL string with optional SSRF protection.
+ *
+ * Throws UrlSafetyError if the URL is invalid, uses a non-http(s) protocol,
+ * points to a blocked hostname, or (when ssrfProtection=true) resolves to a
+ * private IP address.
+ */
+export async function validateUrl(urlStr, opts = {}) {
+    const ssrfProtection = opts.ssrfProtection ?? true;
+    const resolveDns = opts.resolveDns ?? ssrfProtection;
+    if (!urlStr || typeof urlStr !== "string") {
+        throw new UrlSafetyError("URL is required.");
+    }
+    // Reject file:// and other local protocol schemes.
+    const trimmed = urlStr.trim();
+    if (/^(file|ftp|gopher|dict|ldap|data|blob):/i.test(trimmed)) {
+        throw new UrlSafetyError(`Protocol not allowed for SEO fetch: ${trimmed}`);
+    }
+    // Auto-prepend https:// if missing a protocol.
+    let normalized = trimmed;
+    if (!/^https?:\/\//i.test(normalized)) {
+        normalized = `https://${normalized}`;
+    }
+    let parsed;
+    try {
+        parsed = new URL(normalized);
+    }
+    catch {
+        throw new UrlSafetyError(`Invalid URL: ${urlStr}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new UrlSafetyError(`Only http and https protocols are allowed, got: ${parsed.protocol}`);
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    if (BLOCKED_HOSTNAMES.has(hostname)) {
+        throw new UrlSafetyError(`Blocked hostname: ${hostname}`);
+    }
+    // Check for direct IP literals.
+    const ipFamily = isIP(hostname.replace(/^\[|\]$/g, ""));
+    if (ipFamily && isPrivateIp(hostname.replace(/^\[|\]$/g, ""))) {
+        throw new UrlSafetyError(`URL points to a private IP address: ${hostname}`);
+    }
+    let ips = [];
+    if (resolveDns && !ipFamily) {
+        try {
+            const records = await lookup(hostname, { all: true });
+            ips = records.map((r) => r.address);
+            if (ssrfProtection) {
+                for (const ip of ips) {
+                    if (isPrivateIp(ip)) {
+                        throw new UrlSafetyError(`Hostname ${hostname} resolves to private IP ${ip}. Blocked by SSRF protection.`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (err instanceof UrlSafetyError)
+                throw err;
+            // DNS resolution failure is not necessarily an error for SSRF — the fetch
+            // will fail naturally. But we surface it if the caller wanted DNS.
+            if (resolveDns && !ssrfProtection) {
+                // non-fatal: continue without IPs
+            }
+        }
+    }
+    return {
+        href: parsed.href,
+        protocol: parsed.protocol,
+        hostname: parsed.hostname,
+        port: parsed.port,
+        pathname: parsed.pathname,
+        search: parsed.search,
+        ips,
+    };
+}
+/** Quick synchronous URL validation without DNS resolution. */
+export function validateUrlBasic(urlStr) {
+    if (!urlStr || typeof urlStr !== "string") {
+        throw new UrlSafetyError("URL is required.");
+    }
+    const trimmed = urlStr.trim();
+    if (/^(file|ftp|gopher|dict|ldap|data|blob):/i.test(trimmed)) {
+        throw new UrlSafetyError(`Protocol not allowed: ${trimmed}`);
+    }
+    let normalized = trimmed;
+    if (!/^https?:\/\//i.test(normalized)) {
+        normalized = `https://${normalized}`;
+    }
+    let parsed;
+    try {
+        parsed = new URL(normalized);
+    }
+    catch {
+        throw new UrlSafetyError(`Invalid URL: ${urlStr}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new UrlSafetyError(`Only http/https allowed: ${parsed.protocol}`);
+    }
+    return {
+        href: parsed.href,
+        protocol: parsed.protocol,
+        hostname: parsed.hostname,
+        port: parsed.port,
+        pathname: parsed.pathname,
+        search: parsed.search,
+        ips: [],
+    };
+}
+/** Normalize a URL for baseline matching (strip UTM, sort params, lowercase host). */
+export function normalizeUrl(url) {
+    const UTM_PARAMS = new Set(["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"]);
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return url;
+    }
+    parsed.hostname = parsed.hostname.toLowerCase();
+    // Strip default ports.
+    if ((parsed.protocol === "http:" && parsed.port === "80") || (parsed.protocol === "https:" && parsed.port === "443")) {
+        parsed.port = "";
+    }
+    // Remove UTM params.
+    const params = new URLSearchParams(parsed.search);
+    for (const key of [...params.keys()]) {
+        if (UTM_PARAMS.has(key.toLowerCase())) {
+            params.delete(key);
+        }
+    }
+    params.sort();
+    parsed.search = params.toString();
+    // Strip trailing slash (except bare domain).
+    if (parsed.pathname.length > 1 && parsed.pathname.endsWith("/")) {
+        parsed.pathname = parsed.pathname.replace(/\/+$/, "");
+    }
+    return parsed.href;
+}
+/** Hash a normalized URL for baseline deduplication. */
+export function urlHash(url) {
+    return createHash("sha256").update(normalizeUrl(url)).digest("hex").slice(0, 16);
+}

package/dist/sdk/coding-agent/core/extensions/native-extensions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-extensions.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/extensions/native-extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,aAAa,CAAC;IAChD;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAC;IACxB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,uBAAuB,EAkEtD,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAElF;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAIjF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC,CASD"}
+{"version":3,"file":"native-extensions.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/extensions/native-extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,aAAa,CAAC;IAChD;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAC;IACxB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,uBAAuB,EA8EtD,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAElF;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAIjF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC,CASD"}

package/dist/sdk/coding-agent/core/extensions/native-extensions.js

@@ -77,6 +77,17 @@ export const NATIVE_EXTENSIONS = [
         defaultEnabled: true,
         tags: ["vision", "images"],
     },
+    {
+        id: "seo",
+        label: "SEO Analysis",
+        description: "Native SEO audit tools: on-page parsing, technical checks, content quality, " +
+            "Schema.org detection/generation, sitemap, images, preload/bfcache, agent UX, " +
+            "parasite risk, drift monitoring, and full audit orchestration. No external API keys required.",
+        category: "automation",
+        entryPath: "src/extensions/seo/index.ts",
+        defaultEnabled: true,
+        tags: ["seo", "audit", "marketing"],
+    },
 ];
 /**
  * Look up a native extension by id. Returns undefined for unknown ids.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.9.42",
+  "version": "0.9.43",
   "description": "AI coding agent for Aexol with relay-based browser access.",
   "type": "module",
   "private": false,