backpack-ontology 0.2.25 → 0.3.0

package/dist/core/remote-fetch.js

@@ -0,0 +1,338 @@
+// ============================================================
+// Hardened HTTPS fetch for remote learning graphs.
+//
+// Threats this module defends against:
+//   1. SSRF — a malicious URL points at the user's private network
+//      (router admin, cloud metadata, internal services)
+//   2. DNS rebinding — a hostname resolves once for validation,
+//      then to a different IP for the actual request
+//   3. Resource exhaustion — slow loris, infinite stream, oversized body
+//   4. Redirect loops to private addresses
+//
+// The contract:
+//   - HTTPS only
+//   - DNS resolved once; the IP is checked against a private-range
+//     blocklist; the request is dispatched against the IP directly
+//     so DNS rebinding cannot redirect to a different host
+//   - Hard size cap (default 10 MB)
+//   - Hard total timeout (15s) and connect timeout (5s)
+//   - Max 3 redirects, each re-validated
+//   - Returns the body bytes plus an ETag if present
+// ============================================================
+import * as https from "node:https";
+import * as dns from "node:dns/promises";
+import * as net from "node:net";
+import { URL } from "node:url";
+// --- Defaults ---
+export const REMOTE_FETCH_DEFAULTS = {
+    maxBytes: 10 * 1024 * 1024, // 10 MB
+    totalTimeoutMs: 15_000,
+    connectTimeoutMs: 5_000,
+    maxRedirects: 3,
+};
+// --- Errors ---
+export class RemoteFetchError extends Error {
+    code;
+    url;
+    constructor(message, code, url) {
+        super(message);
+        this.code = code;
+        this.url = url;
+        this.name = "RemoteFetchError";
+    }
+}
+/**
+ * Fetch a remote URL with full SSRF / size / timeout protections.
+ *
+ * Throws RemoteFetchError on any policy violation, network error,
+ * or oversized response.
+ */
+export async function remoteFetch(rawUrl, options = {}) {
+    const opts = {
+        maxBytes: options.maxBytes ?? REMOTE_FETCH_DEFAULTS.maxBytes,
+        totalTimeoutMs: options.totalTimeoutMs ?? REMOTE_FETCH_DEFAULTS.totalTimeoutMs,
+        connectTimeoutMs: options.connectTimeoutMs ?? REMOTE_FETCH_DEFAULTS.connectTimeoutMs,
+        maxRedirects: options.maxRedirects ?? REMOTE_FETCH_DEFAULTS.maxRedirects,
+        ifNoneMatch: options.ifNoneMatch,
+    };
+    let currentUrl = rawUrl;
+    let redirectCount = 0;
+    const startedAt = Date.now();
+    while (true) {
+        if (Date.now() - startedAt > opts.totalTimeoutMs) {
+            throw new RemoteFetchError("total fetch timeout exceeded", "TIMEOUT", currentUrl);
+        }
+        const parsed = parseAndValidateUrl(currentUrl);
+        const resolvedIp = await resolveAndCheckHost(parsed.hostname);
+        const remaining = opts.totalTimeoutMs - (Date.now() - startedAt);
+        const response = await singleRequest(parsed, resolvedIp, {
+            maxBytes: opts.maxBytes,
+            totalTimeoutMs: remaining,
+            connectTimeoutMs: opts.connectTimeoutMs,
+            ifNoneMatch: opts.ifNoneMatch,
+        });
+        // 304 Not Modified — no body, return immediately
+        if (response.status === 304) {
+            return {
+                body: "",
+                bytes: 0,
+                etag: response.etag,
+                finalUrl: currentUrl,
+                status: 304,
+                notModified: true,
+            };
+        }
+        // Redirect handling
+        if (response.status >= 300 && response.status < 400 && response.location) {
+            if (redirectCount >= opts.maxRedirects) {
+                throw new RemoteFetchError(`too many redirects (max ${opts.maxRedirects})`, "TOO_MANY_REDIRECTS", currentUrl);
+            }
+            // Resolve relative redirects against the current URL
+            const nextUrl = new URL(response.location, currentUrl).toString();
+            redirectCount++;
+            currentUrl = nextUrl;
+            continue;
+        }
+        if (response.status < 200 || response.status >= 300) {
+            throw new RemoteFetchError(`HTTP ${response.status}`, "HTTP_ERROR", currentUrl);
+        }
+        return {
+            body: response.body,
+            bytes: response.bytes,
+            etag: response.etag,
+            finalUrl: currentUrl,
+            status: response.status,
+            notModified: false,
+        };
+    }
+}
+function parseAndValidateUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new RemoteFetchError(`invalid URL: ${rawUrl}`, "INVALID_URL", rawUrl);
+    }
+    if (url.protocol !== "https:") {
+        throw new RemoteFetchError(`only https:// URLs are allowed (got ${url.protocol})`, "INVALID_SCHEME", rawUrl);
+    }
+    if (!url.hostname) {
+        throw new RemoteFetchError("URL has no hostname", "INVALID_URL", rawUrl);
+    }
+    // Reject userinfo (https://user:pass@host) which can confuse parsers
+    if (url.username || url.password) {
+        throw new RemoteFetchError("URLs with userinfo are not allowed", "INVALID_URL", rawUrl);
+    }
+    // Node's URL parser keeps IPv6 brackets in `hostname` (e.g. "[::1]").
+    // Strip them so net.isIP() and DNS resolution work correctly.
+    let hostname = url.hostname;
+    if (hostname.startsWith("[") && hostname.endsWith("]")) {
+        hostname = hostname.slice(1, -1);
+    }
+    return {
+        href: url.href,
+        hostname,
+        port: url.port ? parseInt(url.port, 10) : 443,
+        pathname: url.pathname || "/",
+        search: url.search || "",
+    };
+}
+/**
+ * Resolves a hostname to an IP and rejects if the IP is in a private,
+ * loopback, link-local, multicast, or otherwise reserved range.
+ *
+ * Returns the resolved IP. Callers should dispatch the request against
+ * the IP directly to prevent DNS rebinding.
+ */
+async function resolveAndCheckHost(hostname) {
+    // If the hostname is already a literal IP, check it directly
+    if (net.isIP(hostname)) {
+        if (isBlockedIp(hostname)) {
+            throw new RemoteFetchError(`IP address ${hostname} is in a blocked range`, "BLOCKED_IP");
+        }
+        return hostname;
+    }
+    let addrs;
+    try {
+        addrs = await dns.lookup(hostname, { all: true, verbatim: true });
+    }
+    catch (err) {
+        throw new RemoteFetchError(`DNS lookup failed: ${err.message}`, "DNS_ERROR");
+    }
+    if (addrs.length === 0) {
+        throw new RemoteFetchError("DNS lookup returned no addresses", "DNS_ERROR");
+    }
+    // Check ALL returned addresses — if any is private, refuse the whole hostname
+    for (const a of addrs) {
+        if (isBlockedIp(a.address)) {
+            throw new RemoteFetchError(`hostname ${hostname} resolves to blocked IP ${a.address}`, "BLOCKED_IP");
+        }
+    }
+    return addrs[0].address;
+}
+/**
+ * Returns true if the IP is in a private, loopback, link-local,
+ * multicast, broadcast, or reserved range. Both IPv4 and IPv6.
+ */
+export function isBlockedIp(ip) {
+    if (net.isIPv4(ip)) {
+        return isBlockedIpv4(ip);
+    }
+    if (net.isIPv6(ip)) {
+        return isBlockedIpv6(ip);
+    }
+    return true; // unknown family — block by default
+}
+function isBlockedIpv4(ip) {
+    const parts = ip.split(".").map((p) => parseInt(p, 10));
+    if (parts.length !== 4 || parts.some((p) => isNaN(p) || p < 0 || p > 255)) {
+        return true;
+    }
+    const [a, b] = parts;
+    // 0.0.0.0/8 — "this network"
+    if (a === 0)
+        return true;
+    // 10.0.0.0/8 — private
+    if (a === 10)
+        return true;
+    // 100.64.0.0/10 — CGNAT shared address space
+    if (a === 100 && b >= 64 && b <= 127)
+        return true;
+    // 127.0.0.0/8 — loopback
+    if (a === 127)
+        return true;
+    // 169.254.0.0/16 — link-local (includes AWS/GCP metadata 169.254.169.254)
+    if (a === 169 && b === 254)
+        return true;
+    // 172.16.0.0/12 — private
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    // 192.0.0.0/24, 192.0.2.0/24 — IETF protocol assignments / TEST-NET-1
+    if (a === 192 && b === 0)
+        return true;
+    // 192.168.0.0/16 — private
+    if (a === 192 && b === 168)
+        return true;
+    // 198.18.0.0/15 — benchmarking
+    if (a === 198 && (b === 18 || b === 19))
+        return true;
+    // 198.51.100.0/24 — TEST-NET-2
+    if (a === 198 && b === 51)
+        return true;
+    // 203.0.113.0/24 — TEST-NET-3
+    if (a === 203 && b === 0)
+        return true;
+    // 224.0.0.0/4 — multicast
+    if (a >= 224 && a <= 239)
+        return true;
+    // 240.0.0.0/4 — reserved + 255.255.255.255 broadcast
+    if (a >= 240)
+        return true;
+    return false;
+}
+function isBlockedIpv6(ip) {
+    const lower = ip.toLowerCase();
+    // ::1 — loopback
+    if (lower === "::1")
+        return true;
+    // :: — unspecified
+    if (lower === "::")
+        return true;
+    // ::ffff:x.x.x.x — IPv4-mapped, recheck the IPv4
+    const v4MappedMatch = lower.match(/^::ffff:([\d.]+)$/);
+    if (v4MappedMatch) {
+        return isBlockedIpv4(v4MappedMatch[1]);
+    }
+    // fc00::/7 — unique local
+    if (lower.startsWith("fc") || lower.startsWith("fd"))
+        return true;
+    // fe80::/10 — link-local
+    if (lower.startsWith("fe8") || lower.startsWith("fe9") ||
+        lower.startsWith("fea") || lower.startsWith("feb"))
+        return true;
+    // ff00::/8 — multicast
+    if (lower.startsWith("ff"))
+        return true;
+    // 2001:db8::/32 — documentation
+    if (lower.startsWith("2001:db8:"))
+        return true;
+    return false;
+}
+function singleRequest(parsed, resolvedIp, opts) {
+    return new Promise((resolve, reject) => {
+        const headers = {
+            Host: parsed.hostname, // SNI / virtual host header still uses the name
+            "User-Agent": "backpack-remote-fetch/1.0",
+            Accept: "application/json",
+        };
+        if (opts.ifNoneMatch) {
+            headers["If-None-Match"] = opts.ifNoneMatch;
+        }
+        const req = https.request({
+            host: resolvedIp,
+            port: parsed.port,
+            path: parsed.pathname + parsed.search,
+            method: "GET",
+            headers,
+            servername: parsed.hostname, // SNI
+            // Strict TLS — no insecure fallback
+            rejectUnauthorized: true,
+            timeout: opts.connectTimeoutMs,
+        }, (res) => {
+            const status = res.statusCode || 0;
+            const etag = res.headers.etag || null;
+            const location = res.headers.location || null;
+            // 304 / 3xx — no body needed (or shouldn't read it)
+            if (status === 304 || (status >= 300 && status < 400)) {
+                res.resume(); // drain
+                resolve({ status, body: "", bytes: 0, etag, location });
+                return;
+            }
+            // Check declared content-length up front
+            const declared = parseInt(res.headers["content-length"] || "0", 10);
+            if (declared > opts.maxBytes) {
+                req.destroy();
+                reject(new RemoteFetchError(`Content-Length ${declared} exceeds max ${opts.maxBytes}`, "TOO_LARGE", parsed.href));
+                return;
+            }
+            const chunks = [];
+            let totalBytes = 0;
+            res.on("data", (chunk) => {
+                totalBytes += chunk.length;
+                if (totalBytes > opts.maxBytes) {
+                    req.destroy();
+                    reject(new RemoteFetchError(`response exceeds max ${opts.maxBytes} bytes`, "TOO_LARGE", parsed.href));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            res.on("end", () => {
+                const body = Buffer.concat(chunks).toString("utf8");
+                resolve({ status, body, bytes: totalBytes, etag, location });
+            });
+            res.on("error", (err) => {
+                reject(new RemoteFetchError(`response error: ${err.message}`, "NETWORK_ERROR", parsed.href));
+            });
+        });
+        // Total timeout (separate from connect timeout)
+        const totalTimer = setTimeout(() => {
+            req.destroy();
+            reject(new RemoteFetchError("request timeout exceeded", "TIMEOUT", parsed.href));
+        }, opts.totalTimeoutMs);
+        req.on("timeout", () => {
+            req.destroy();
+            reject(new RemoteFetchError("connect timeout exceeded", "CONNECT_TIMEOUT", parsed.href));
+        });
+        req.on("error", (err) => {
+            clearTimeout(totalTimer);
+            // Already rejected above? Promise is idempotent, second reject is no-op
+            reject(new RemoteFetchError(`network error: ${err.message}`, "NETWORK_ERROR", parsed.href));
+        });
+        req.on("close", () => {
+            clearTimeout(totalTimer);
+        });
+        req.end();
+    });
+}
+//# sourceMappingURL=remote-fetch.js.map

package/dist/core/remote-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-fetch.js","sourceRoot":"","sources":["../../src/core/remote-fetch.ts"],"names":[],"mappings":"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"}

package/dist/core/remote-registry.d.ts

@@ -0,0 +1,95 @@
+import type { LearningGraphData } from "./types.js";
+export interface RemoteEntry {
+    /** Local alias used in the viewer / MCP. Unique within the registry. */
+    name: string;
+    /** Source URL (must be https://). */
+    url: string;
+    /** Optional human-readable source label (e.g. "github:user/repo"). */
+    source?: string;
+    /** ISO timestamp when first registered. */
+    addedAt: string;
+    /** ISO timestamp of the last successful fetch. */
+    lastFetched: string;
+    /** Last seen ETag, for conditional GETs. */
+    etag: string | null;
+    /** SHA256 of the last fetched body. */
+    sha256: string;
+    /** If true, refetch refuses to overwrite when sha256 changes. */
+    pinned: boolean;
+    /** Size in bytes of the cached body. */
+    sizeBytes: number;
+}
+export interface RegistryFile {
+    version: number;
+    remotes: RemoteEntry[];
+}
+export declare class RemoteRegistryError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare class RemoteRegistry {
+    private baseDir;
+    constructor(baseDir?: string);
+    private registryFile;
+    private cacheDir;
+    private cacheFile;
+    /**
+     * Ensures the base directory and cache directory exist.
+     * Safe to call multiple times.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Reads the registry file. Returns an empty registry if the file
+     * doesn't exist yet.
+     */
+    load(): Promise<RegistryFile>;
+    /**
+     * Atomically writes the registry file.
+     */
+    private save;
+    /**
+     * List all registered remotes.
+     */
+    list(): Promise<RemoteEntry[]>;
+    /**
+     * Look up a single remote by name.
+     */
+    get(name: string): Promise<RemoteEntry | null>;
+    /**
+     * Register a new remote: validate the name, fetch the URL, validate
+     * the graph schema, write to cache, and append to the registry.
+     *
+     * Throws if the name already exists, if the URL fails to fetch, or
+     * if the schema validation fails.
+     *
+     * The caller is responsible for ensuring the name does not collide
+     * with a local graph (this module doesn't know about local graphs).
+     */
+    register(opts: {
+        name: string;
+        url: string;
+        source?: string;
+        pin?: boolean;
+    }): Promise<RemoteEntry>;
+    /**
+     * Refetch a registered remote. Uses ETag for conditional GET.
+     *
+     * If pinned and the SHA256 changes, throws RemoteRegistryError with
+     * code "PIN_VIOLATION" without overwriting the cache.
+     */
+    refresh(name: string): Promise<{
+        entry: RemoteEntry;
+        changed: boolean;
+        notModified: boolean;
+    }>;
+    /**
+     * Remove a remote from the registry and delete its cache file.
+     */
+    unregister(name: string): Promise<void>;
+    /**
+     * Load the cached graph contents for a registered remote.
+     * Throws if the remote is not registered or the cache file is missing.
+     */
+    loadCached(name: string): Promise<LearningGraphData>;
+}
+//# sourceMappingURL=remote-registry.d.ts.map

package/dist/core/remote-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-registry.d.ts","sourceRoot":"","sources":["../../src/core/remote-registry.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAIpD,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAC;IAChB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAOD,qBAAa,mBAAoB,SAAQ,KAAK;aAG1B,IAAI,EAAE,MAAM;gBAD5B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM;CAK/B;AAuBD,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,CAAC,EAAE,MAAM;IAI5B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,SAAS;IAcjB;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,YAAY,CAAC;IAwBnC;;OAEG;YACW,IAAI;IAMlB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAKpC;;OAEG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAMpD;;;;;;;;;OASG;IACG,QAAQ,CAAC,IAAI,EAAE;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,GAAG,CAAC,EAAE,OAAO,CAAC;KACf,GAAG,OAAO,CAAC,WAAW,CAAC;IA0ExB;;;;;OAKG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QACnC,KAAK,EAAE,WAAW,CAAC;QACnB,OAAO,EAAE,OAAO,CAAC;QACjB,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;IAgFF;;OAEG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB7C;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAwB3D"}