@bedolla/enrivision 0.1.1 → 0.1.3

package/dist/shared/mediaUrlFetcher.js

@@ -0,0 +1,269 @@
+/**
+ * BOUNDED MEDIA URL FETCHER
+ *
+ * Downloads one http(s) media resource into a temporary directory so the
+ * upload pipeline can treat it like any local file.
+ *
+ * Protections: 64 MiB size cap, 60 s timeout, SSRF guard (literal private
+ * addresses rejected, DNS-resolved addresses rejected, per-hop validation of
+ * up to 3 redirects), and an owned cleanup callback.
+ *
+ * @module shared/mediaUrlFetcher
+ */
+import { isIP } from "node:net";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Immutable media URL fetch result record.
+ */
+class MediaUrlFetchResultRecord {
+    localPath;
+    contentType;
+    cleanupCallback;
+    /**
+     * Creates one fetch result.
+     *
+     * @param localPath - Downloaded file path.
+     * @param contentType - Reported content type.
+     * @param cleanupCallback - Owned cleanup callback.
+     */
+    constructor(localPath, contentType, cleanupCallback) {
+        this.localPath = localPath;
+        this.contentType = contentType;
+        this.cleanupCallback = cleanupCallback;
+    }
+    /**
+     * @inheritdoc
+     */
+    async cleanup() {
+        await this.cleanupCallback();
+    }
+}
+/**
+ * Downloads bounded http(s) media into a temporary directory.
+ */
+export class MediaUrlFetcher {
+    /**
+     * Maximum accepted download size in bytes.
+     */
+    static MAX_BYTES = 64 * 1024 * 1024;
+    /**
+     * Download timeout in milliseconds.
+     */
+    static TIMEOUT_MS = 60_000;
+    /**
+     * Maximum followed redirects (each hop re-validated).
+     */
+    static MAX_REDIRECTS = 3;
+    /**
+     * Fetch implementation (injectable for tests).
+     */
+    fetchImpl;
+    /**
+     * Host address resolver (injectable for tests).
+     */
+    resolveHostAddresses;
+    /**
+     * Creates one media URL fetcher.
+     *
+     * @param fetchImpl - Optional fetch override for tests.
+     * @param resolveHostAddresses - Optional DNS resolver override for tests.
+     */
+    constructor(fetchImpl, resolveHostAddresses) {
+        this.fetchImpl = fetchImpl ?? fetch;
+        this.resolveHostAddresses =
+            resolveHostAddresses ??
+                (async (hostname) => {
+                    const results = await dnsLookup(hostname, { all: true });
+                    return results.map((result) => result.address);
+                });
+    }
+    /**
+     * Reports whether one input looks like an accepted http(s) URL.
+     *
+     * @param value - Raw path argument.
+     * @returns True for http/https URLs.
+     */
+    static isHttpUrl(value) {
+        return /^https?:\/\//iu.test(String(value ?? "").trim());
+    }
+    /**
+     * Downloads one http(s) URL into a temporary directory.
+     *
+     * @param url - Absolute http(s) URL.
+     * @returns Bounded fetch result with owned cleanup.
+     * @throws Error when the destination is blocked, too large, or the download fails.
+     */
+    async fetch(url) {
+        let currentUrl = String(url ?? "").trim();
+        if (!MediaUrlFetcher.isHttpUrl(currentUrl)) {
+            throw new Error("Sólo se aceptan URLs http(s) en path/paths.");
+        }
+        const timeoutSignal = AbortSignal.timeout(MediaUrlFetcher.TIMEOUT_MS);
+        let response = await this.requestValidated(currentUrl, timeoutSignal);
+        for (let redirectCount = 0; redirectCount < MediaUrlFetcher.MAX_REDIRECTS; redirectCount += 1) {
+            if (response.status < 301 || response.status > 308) {
+                break;
+            }
+            const location = response.headers.get("location");
+            if (!location) {
+                break;
+            }
+            currentUrl = new URL(location, currentUrl).toString();
+            if (!MediaUrlFetcher.isHttpUrl(currentUrl)) {
+                throw new Error("La redirección apunta fuera de http(s).");
+            }
+            response = await this.requestValidated(currentUrl, timeoutSignal);
+        }
+        if (!response.ok) {
+            throw new Error(`La URL respondió HTTP ${String(response.status)}.`);
+        }
+        const declaredLengthHeader = response.headers.get("content-length");
+        if (declaredLengthHeader !== null &&
+            Number(declaredLengthHeader) > MediaUrlFetcher.MAX_BYTES) {
+            throw new Error(`El archivo remoto excede el límite de 64 MiB.`);
+        }
+        const buffer = await response.arrayBuffer();
+        if (buffer.byteLength > MediaUrlFetcher.MAX_BYTES) {
+            throw new Error(`El archivo remoto excede el límite de 64 MiB.`);
+        }
+        const contentType = (response.headers.get("content-type") ?? "")
+            .split(";", 1)[0]
+            .trim()
+            .toLowerCase();
+        const temporaryDirectory = await mkdtemp(join(tmpdir(), "enrivision-url-"));
+        const localPath = join(temporaryDirectory, this.deriveFileName(currentUrl, contentType));
+        try {
+            await writeFile(localPath, Buffer.from(buffer));
+        }
+        catch (error) {
+            await rm(temporaryDirectory, { recursive: true, force: true });
+            throw new Error(`No se pudo guardar la media descargada: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return new MediaUrlFetchResultRecord(localPath, contentType, async () => {
+            await rm(temporaryDirectory, { recursive: true, force: true });
+        });
+    }
+    /**
+     * Performs one fetch request after validating the destination addresses.
+     *
+     * @param url - Candidate URL (already normalized).
+     * @param timeoutSignal - Timeout signal shared by every hop.
+     * @returns Fetch response.
+     * @throws Error when the hostname resolves to a blocked address or the request fails.
+     */
+    async requestValidated(url, timeoutSignal) {
+        await this.assertPublicDestination(url);
+        try {
+            return await this.fetchImpl(url, { signal: timeoutSignal, redirect: "manual" });
+        }
+        catch (error) {
+            throw new Error(`La descarga de media falló: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Validates that the URL hostname is not a private/loopback/link-local target.
+     *
+     * @param url - Candidate URL.
+     * @throws Error when a literal or resolved address is blocked.
+     */
+    async assertPublicDestination(url) {
+        const hostname = new URL(url).hostname.replace(/^\[|\]$/gu, "");
+        if (hostname === "localhost") {
+            throw new Error("Destino bloqueado: no se permiten hosts locales ni redes privadas.");
+        }
+        if (isIP(hostname) !== 0) {
+            this.assertPublicAddress(hostname);
+            return;
+        }
+        const addresses = await this.resolveHostAddresses(hostname);
+        if (addresses.length === 0) {
+            throw new Error("No se pudo resolver el host antes de descargar la media.");
+        }
+        for (const address of addresses) {
+            this.assertPublicAddress(address);
+        }
+    }
+    /**
+     * Rejects private, loopback, link-local, and unspecified addresses.
+     *
+     * @param address - Literal IP address.
+     * @throws Error when the address belongs to a blocked range.
+     */
+    assertPublicAddress(address) {
+        const version = isIP(address);
+        if (version === 4) {
+            const octets = address.split(".").map((part) => Number(part));
+            const [first = 0, second = 0] = octets;
+            const blocked = first === 0 ||
+                first === 10 ||
+                first === 127 ||
+                (first === 169 && second === 254) ||
+                (first === 172 && second >= 16 && second <= 31) ||
+                (first === 192 && second === 168) ||
+                first >= 224;
+            if (blocked) {
+                throw new Error("Destino bloqueado: no se permiten hosts locales ni redes privadas.");
+            }
+            return;
+        }
+        if (version === 6) {
+            const normalized = address.toLowerCase();
+            const blocked = normalized === "::" ||
+                normalized === "::1" ||
+                normalized.startsWith("fc") ||
+                normalized.startsWith("fd") ||
+                normalized.startsWith("fe8") ||
+                normalized.startsWith("fe9") ||
+                normalized.startsWith("fea") ||
+                normalized.startsWith("feb");
+            const mappedV4 = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/u.exec(normalized)?.[1] ?? null;
+            if (mappedV4 !== null) {
+                this.assertPublicAddress(mappedV4);
+                return;
+            }
+            if (blocked) {
+                throw new Error("Destino bloqueado: no se permiten hosts locales ni redes privadas.");
+            }
+        }
+    }
+    /**
+     * Derives one safe file name for the downloaded media.
+     *
+     * @param url - Source URL.
+     * @param contentType - Reported content type.
+     * @returns Bounded file name with a recognized extension.
+     */
+    deriveFileName(url, contentType) {
+        const withoutQuery = url.split("?")[0] ?? url;
+        const baseName = withoutQuery.split("/").pop() ?? "media";
+        const sanitized = baseName.replace(/[^A-Za-z0-9._-]/gu, "").slice(0, 80);
+        if (sanitized.length > 0 && /\.[A-Za-z0-9]{2,5}$/u.test(sanitized)) {
+            return sanitized;
+        }
+        const extension = this.extensionForContentType(contentType);
+        return `${sanitized.length > 0 ? sanitized : "media"}${extension}`;
+    }
+    /**
+     * Resolves one default extension for a content type.
+     *
+     * @param contentType - Reported content type.
+     * @returns Extension with leading dot.
+     */
+    extensionForContentType(contentType) {
+        if (contentType.startsWith("image/"))
+            return ".png";
+        if (contentType.startsWith("video/"))
+            return ".mp4";
+        if (contentType.startsWith("audio/"))
+            return ".mp3";
+        if (contentType.includes("pdf"))
+            return ".pdf";
+        if (contentType.includes("tar"))
+            return ".tar";
+        return ".bin";
+    }
+}
+//# sourceMappingURL=mediaUrlFetcher.js.map

package/dist/shared/mediaUrlFetcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaUrlFetcher.js","sourceRoot":"","sources":["../../src/shared/mediaUrlFetcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA2BjC;;GAEG;AACH,MAAM,yBAAyB;IASX;IACA;IACC;IAVnB;;;;;;OAMG;IACH,YACkB,SAAiB,EACjB,WAAmB,EAClB,eAAoC;QAFrC,cAAS,GAAT,SAAS,CAAQ;QACjB,gBAAW,GAAX,WAAW,CAAQ;QAClB,oBAAe,GAAf,eAAe,CAAqB;IACpD,CAAC;IAEJ;;OAEG;IACI,KAAK,CAAC,OAAO;QAClB,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC;IAC/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,eAAe;IAC1B;;OAEG;IACK,MAAM,CAAU,SAAS,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;IAErD;;OAEG;IACK,MAAM,CAAU,UAAU,GAAG,MAAM,CAAC;IAE5C;;OAEG;IACK,MAAM,CAAU,aAAa,GAAG,CAAC,CAAC;IAE1C;;OAEG;IACc,SAAS,CAAe;IAEzC;;OAEG;IACc,oBAAoB,CAAsB;IAE3D;;;;;OAKG;IACH,YAAmB,SAAwB,EAAE,oBAA0C;QACrF,IAAI,CAAC,SAAS,GAAG,SAAS,IAAI,KAAK,CAAC;QACpC,IAAI,CAAC,oBAAoB;YACvB,oBAAoB;gBACpB,CAAC,KAAK,EAAE,QAAgB,EAA8B,EAAE;oBACtD,MAAM,OAAO,GAA+B,MAAM,SAAS,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;oBACrF,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBACjD,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,SAAS,CAAC,KAAa;QACnC,OAAO,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,KAAK,CAAC,GAAW;QAC5B,IAAI,UAAU,GAAW,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAClD,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACjE,CAAC;QAED,MAAM,aAAa,GAAgB,WAAW,CAAC,OAAO,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;QACnF,IAAI,QAAQ,GAAa,MAAM,IAAI,CAAC,gBAAgB,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;QAEhF,KAAK,IAAI,aAAa,GAAG,CAAC,EAAE,aAAa,GAAG,eAAe,CAAC,aAAa,EAAE,aAAa,IAAI,CAAC,EAAE,CAAC;YAC9F,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;gBACnD,MAAM;YACR,CAAC;YACD,MAAM,QAAQ,GAAkB,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACjE,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM;YACR,CAAC;YACD,UAAU,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,QAAQ,EAAE,CAAC;YACtD,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC3C,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;YAC7D,CAAC;YACD,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;QACpE,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvE,CAAC;QAED,MAAM,oBAAoB,GAAkB,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QACnF,IACE,oBAAoB,KAAK,IAAI;YAC7B,MAAM,CAAC,oBAAoB,CAAC,GAAG,eAAe,CAAC,SAAS,EACxD,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACnE,CAAC;QAED,MAAM,MAAM,GAAgB,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC;QACzD,IAAI,MAAM,CAAC,UAAU,GAAG,eAAe,CAAC,SAAS,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACnE,CAAC;QAED,MAAM,WAAW,GAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;aACrE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE;aACjB,IAAI,EAAE;aACN,WAAW,EAAE,CAAC;QACjB,MAAM,kBAAkB,GAAW,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,iBAAiB,CAAC,CAAC,CAAC;QACpF,MAAM,SAAS,GAAW,IAAI,CAC5B,kBAAkB,EAClB,IAAI,CAAC,cAAc,CAAC,UAAU,EAAE,WAAW,CAAC,CAC7C,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,EAAE,CAAC,kBAAkB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/D,MAAM,IAAI,KAAK,CACb,2CAA2C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACpG,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,yBAAyB,CAAC,SAAS,EAAE,WAAW,EAAE,KAAK,IAAmB,EAAE;YACrF,MAAM,EAAE,CAAC,kBAAkB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACK,KAAK,CAAC,gBAAgB,CAAC,GAAW,EAAE,aAA0B;QACpE,MAAM,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;QAClF,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,+BAA+B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACxF,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,uBAAuB,CAAC,GAAW;QAC/C,MAAM,QAAQ,GAAW,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QACxE,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;QACxF,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YACnC,OAAO;QACT,CAAC;QACD,MAAM,SAAS,GAAsB,MAAM,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QAC/E,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC9E,CAAC;QACD,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,mBAAmB,CAAC,OAAe;QACzC,MAAM,OAAO,GAAW,IAAI,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;YAClB,MAAM,MAAM,GAAsB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;YACjF,MAAM,CAAC,KAAK,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC;YACvC,MAAM,OAAO,GACX,KAAK,KAAK,CAAC;gBACX,KAAK,KAAK,EAAE;gBACZ,KAAK,KAAK,GAAG;gBACb,CAAC,KAAK,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAC;gBACjC,CAAC,KAAK,KAAK,GAAG,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM,IAAI,EAAE,CAAC;gBAC/C,CAAC,KAAK,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAC;gBACjC,KAAK,IAAI,GAAG,CAAC;YACf,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;YACxF,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;YAClB,MAAM,UAAU,GAAW,OAAO,CAAC,WAAW,EAAE,CAAC;YACjD,MAAM,OAAO,GACX,UAAU,KAAK,IAAI;gBACnB,UAAU,KAAK,KAAK;gBACpB,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC;gBAC3B,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC;gBAC3B,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC;gBAC5B,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC;gBAC5B,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC;gBAC5B,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YAC/B,MAAM,QAAQ,GAAkB,gCAAgC,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;YAC/F,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;gBACtB,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;gBACnC,OAAO;YACT,CAAC;YACD,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;YACxF,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACK,cAAc,CAAC,GAAW,EAAE,WAAmB;QACrD,MAAM,YAAY,GAAW,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;QACtD,MAAM,QAAQ,GAAW,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC;QAClE,MAAM,SAAS,GAAW,QAAQ,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACjF,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,sBAAsB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACnE,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,SAAS,GAAW,IAAI,CAAC,uBAAuB,CAAC,WAAW,CAAC,CAAC;QACpE,OAAO,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,GAAG,SAAS,EAAE,CAAC;IACrE,CAAC;IAED;;;;;OAKG;IACK,uBAAuB,CAAC,WAAmB;QACjD,IAAI,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,MAAM,CAAC;QACpD,IAAI,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,MAAM,CAAC;QACpD,IAAI,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,MAAM,CAAC;QACpD,IAAI,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,MAAM,CAAC;QAC/C,IAAI,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,MAAM,CAAC;QAC/C,OAAO,MAAM,CAAC;IAChB,CAAC"}

package/dist/tools/AnalyzeMediaTool.d.ts

@@ -2,26 +2,29 @@
  * ANALYZE MEDIA TOOL
  *
  * Implements the `analyze_media` MCP tool:
- * - Validates local file path
- * - Streams the file to EnriProxy via resumable uploads
+ * - Validates local file paths or http(s) URLs
+ * - Materializes URL inputs via bounded downloads (temporary, owned cleanup)
+ * - Streams the bytes to EnriProxy via resumable uploads
  * - Triggers server-side analysis and returns text-only results
  *
  * @module tools/AnalyzeMediaTool
  */
 import { type EnriProxyClient } from "../client/EnriProxyClient.js";
+import { MediaUrlFetcher } from "../shared/mediaUrlFetcher.js";
 /**
  * Tool parameters for `analyze_media`.
  */
 export interface AnalyzeMediaToolParams {
     /**
-     * Absolute local filesystem path on the MCP host.
+     * Absolute local filesystem path on the MCP host, or one http(s) URL to
+     * download (bounded, temporary) and analyze.
      *
      * @remarks
      * Use `paths` to analyze multiple images in a single call.
      */
     readonly path?: string;
     /**
-     * Absolute local filesystem paths on the MCP host.
+     * Absolute local filesystem paths or http(s) URLs on the MCP host.
      *
      * @remarks
      * When provided, EnriVision uploads the files as a single media-set archive
@@ -198,19 +201,24 @@ export interface AnalyzeMediaToolDeps {
     readonly defaultTimeoutMs: number;
 }
 /**
- * MCP tool that uploads and analyzes local media.
+ * MCP tool that uploads and analyzes local or http(s) URL media.
  */
 export declare class AnalyzeMediaTool {
     /**
      * Tool dependencies.
      */
     private readonly deps;
+    /**
+     * Bounded http(s) media fetcher used when `path`/`paths` carry URLs.
+     */
+    private readonly urlFetcher;
     /**
      * Creates a new {@link AnalyzeMediaTool}.
      *
      * @param deps - Tool dependencies
+     * @param urlFetcher - Optional URL fetcher override for tests
      */
-    constructor(deps: AnalyzeMediaToolDeps);
+    constructor(deps: AnalyzeMediaToolDeps, urlFetcher?: MediaUrlFetcher);
     /**
      * Validates raw MCP tool arguments.
      *
@@ -225,6 +233,19 @@ export declare class AnalyzeMediaTool {
      * @returns Tool result
      */
     execute(params: AnalyzeMediaToolParams): Promise<AnalyzeMediaToolResult>;
+    /**
+     * Resolves the upload content type for one media input.
+     *
+     * @remarks
+     * URL downloads keep their extension-derived type when the extension is
+     * recognized; otherwise the server-reported content type wins over the
+     * generic `application/octet-stream` fallback.
+     *
+     * @param localPath - Local file path (already materialized for URLs)
+     * @param urlContentType - Server-reported content type for downloaded URLs
+     * @returns Effective MIME type
+     */
+    private resolveEffectiveContentType;
     /**
      * Removes internal identifiers (upload ids, routing-only values, etc.) from the
      * extraction payload before returning it to the model.
@@ -270,7 +291,7 @@ export declare class AnalyzeMediaTool {
      * screenshot sets.
      *
      * @param client - EnriProxy client
-     * @param filePaths - Absolute image file paths
+     * @param inputs - Resolved media inputs (local paths, URLs already materialized)
      * @param timeoutMs - Request timeout per HTTP request
      * @param clientTraceId - Client trace id for correlation
      * @returns Upload id for the created tar session

package/dist/tools/AnalyzeMediaTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyzeMediaTool.d.ts","sourceRoot":"","sources":["../../src/tools/AnalyzeMediaTool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AnalyzeMediaTool.d.ts","sourceRoot":"","sources":["../../src/tools/AnalyzeMediaTool.ts"],"names":[],"mappings":"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"}