@bedolla/enrivision 0.1.5 → 0.1.6

package/dist/tools/AnalyzeMediaExtractionSanitizer.js

@@ -0,0 +1,214 @@
+/**
+ * ANALYZE MEDIA EXTRACTION SANITIZER
+ *
+ * Strips routing-only internals from the EnriProxy extraction payload before
+ * it reaches the model. Only upload identifiers, provider-routing identities,
+ * and secret-bearing keys are removed: coverage metadata that EnriProxy
+ * intentionally returns (`detected_media_type`, `analysis_mode_*`,
+ * `multipass`, `models`, `strategy`, `warnings`, `frame_count`, `timeline`)
+ * is preserved so the model can report honest coverage (missing frames).
+ *
+ * Key matching is separator-insensitive (`-`, `_`, `.` stripped): hyphenated
+ * spellings such as `api-key` or `access-token` match like `api_key`.
+ *
+ * @module tools/AnalyzeMediaExtractionSanitizer
+ */
+/**
+ * Internal-only extraction keys stripped at any depth (case-insensitive,
+ * separator-insensitive: matched against the separator-stripped form).
+ *
+ * @remarks
+ * Covers upload identifiers, provider-routing identities, secret-bearing
+ * token variants (`api_key`, `secret`, `refresh_token`, `access_token`,
+ * `auth_token`, `id_token`, bare `token`), and bare bearer material (`jwt`,
+ * `jwk` plus suffixed variants). Coverage and accounting keys such as
+ * `multipass`, `detected_media_type`, `analysis_mode_*`, `models`,
+ * `strategy`, `warnings`, `frame_count`, `timeline`, and the OpenAI usage
+ * block (`prompt_tokens`, `completion_tokens`, `total_tokens`, …) are
+ * explicitly preserved (see {@link PRESERVED_KEYS} and the accounting set).
+ */
+const STRIPPED_KEY_PATTERN = /^(uploadids?.*|provider.*|apikeys?.*|secrets?.*|refreshtokens?.*|accesstokens?.*|authtokens?.*|idtokens?.*|jwts?.*|jwks?.*|tokens?)$/iu;
+/**
+ * Internal routing identifiers that never reach the model.
+ *
+ * @remarks
+ * The anchored pattern above requires a literal `id` after `upload_`, so
+ * `upload_url` would survive it; session/trace ids are plausible server
+ * internals too. Listed explicitly (case-insensitive) instead.
+ */
+const INTERNAL_KEYS = new Set([
+    "sessionid",
+    "clienttraceid",
+    "traceid",
+    "uploadurl",
+    "requestid",
+]);
+/**
+ * Secret-material suffixes stripped at any depth (case-insensitive).
+ *
+ * @remarks
+ * The anchored pattern misses prefixed secrets (`client_secret`,
+ * `my_api_key`) and bearer/authorization material, all of which would
+ * otherwise reach the model. Matched as a suffix so `monkey`-style false
+ * positives cannot strip legitimate metadata.
+ */
+const SECRET_SUFFIX_PATTERN = /(password|passwd|bearer|authorization|authentication|nonce|signature)$/iu;
+/**
+ * Coverage/accounting keys that must survive sanitization even though an
+ * older broader pattern used to strip them.
+ */
+const PRESERVED_KEYS = new Set([
+    "multipass",
+    "detected_media_type",
+    "analysis_mode",
+    "analysis_mode_requested",
+    "analysis_mode_used",
+    "models",
+    "model",
+    "strategy",
+    "warnings",
+    "frame_count",
+    "timeline",
+]);
+/**
+ * Legitimate accounting/metadata keys that must survive sanitization even
+ * though they contain the substring `token`.
+ *
+ * @remarks
+ * Covers the standard OpenAI-compatible usage block (`prompt_tokens`,
+ * `completion_tokens`, `total_tokens`, `input_tokens`, `output_tokens`) plus
+ * reasoning/cache variants. Compared in separator-stripped form (see
+ * {@link normalizeSanitizerKey}) so hyphenated spellings (`prompt-tokens`)
+ * and vendor-prefixed variants (`response_input_tokens`) survive too.
+ */
+const ACCOUNTING_KEYS = new Set([
+    "tokenusage",
+    "tokensused",
+    "tokencount",
+    "prompttokens",
+    "completiontokens",
+    "totaltokens",
+    "inputtokens",
+    "outputtokens",
+    "reasoningtokens",
+    "cachetokens",
+]);
+/**
+ * Normalizes one extraction key for separator-insensitive matching.
+ *
+ * @remarks
+ * Strips `-`, `_`, and `.` after lowercasing so hyphenated secrets
+ * (`api-key`, `access-token`, `provider-id`, `client-secret`, `upload-ids`)
+ * match the same anchored and suffix rules as their underscored spellings.
+ *
+ * @param key - Raw extraction key.
+ * @returns Lowercased key without `-`, `_`, or `.` characters.
+ */
+function normalizeSanitizerKey(key) {
+    return key.toLowerCase().replace(/[-_.]/gu, "");
+}
+/**
+ * Reports whether one separator-stripped key is legitimate usage accounting.
+ *
+ * @remarks
+ * Exact match covers the standard OpenAI-compatible usage block; the
+ * ends-with rule additionally preserves vendor-prefixed variants (for
+ * example `response_input_tokens` → `responseinputtokens`). Preservation is
+ * the fail-open direction here only because every accounting token is a
+ * known usage-counter suffix, never a secret shape.
+ *
+ * @param normalizedKey - Separator-stripped lowercased key (see {@link normalizeSanitizerKey}).
+ * @returns True when the key is accounting and must survive sanitization.
+ */
+function isAccountingKey(normalizedKey) {
+    if (ACCOUNTING_KEYS.has(normalizedKey)) {
+        return true;
+    }
+    for (const token of ACCOUNTING_KEYS) {
+        if (normalizedKey.length > token.length && normalizedKey.endsWith(token)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Object keys that must never be assigned (prototype pollution guard).
+ */
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Sanitizes EnriProxy extraction payloads for model consumption.
+ */
+export class AnalyzeMediaExtractionSanitizer {
+    /**
+     * Removes internal identifiers from the extraction payload.
+     *
+     * @param extraction - Raw extraction object returned by EnriProxy.
+     * @returns Sanitized plain extraction object.
+     */
+    sanitize(extraction) {
+        const stripped = this.stripInternalFields(extraction);
+        if (stripped && typeof stripped === "object" && !Array.isArray(stripped)) {
+            return stripped;
+        }
+        return {};
+    }
+    /**
+     * Recursively strips internal fields from an unknown value.
+     *
+     * @param value - Unknown value to sanitize.
+     * @returns Sanitized value.
+     */
+    stripInternalFields(value) {
+        if (Array.isArray(value)) {
+            return value.map((item) => this.stripInternalFields(item));
+        }
+        if (!value || typeof value !== "object") {
+            return value;
+        }
+        const record = value;
+        const next = {};
+        for (const [key, child] of Object.entries(record)) {
+            if (UNSAFE_KEYS.has(key)) {
+                continue;
+            }
+            const lowered = key.toLowerCase();
+            if (PRESERVED_KEYS.has(lowered)) {
+                next[key] = this.stripInternalFields(child);
+                continue;
+            }
+            // Separator-insensitive matching (F10): hyphens, underscores, and dots
+            // are stripped before every rule below, so `api-key`, `access-token`,
+            // `provider-id`, `client-secret`, and `upload-ids` match exactly like
+            // their underscored spellings. Accounting is checked first so usage
+            // counters (including hyphenated and vendor-prefixed variants) survive
+            // the `token` suffix sweep.
+            const normalized = normalizeSanitizerKey(key);
+            if (isAccountingKey(normalized)) {
+                next[key] = this.stripInternalFields(child);
+                continue;
+            }
+            if (STRIPPED_KEY_PATTERN.test(normalized)) {
+                continue;
+            }
+            if (INTERNAL_KEYS.has(normalized)) {
+                continue;
+            }
+            // Substring/suffix secret sweep. Catches prefixed secrets the anchored
+            // pattern misses (`client_secret`, `my_token`) plus bare `jwt`/`jwk`
+            // bearer material and request-signing leftovers (`nonce`, `signature`).
+            if (normalized.includes("secret") ||
+                normalized.includes("apikey") ||
+                normalized.includes("privatekey") ||
+                normalized.includes("credential") ||
+                normalized.includes("password") ||
+                normalized.includes("passwd") ||
+                /tokens?$/u.test(normalized) ||
+                SECRET_SUFFIX_PATTERN.test(normalized)) {
+                continue;
+            }
+            next[key] = this.stripInternalFields(child);
+        }
+        return next;
+    }
+}
+//# sourceMappingURL=AnalyzeMediaExtractionSanitizer.js.map

package/dist/tools/AnalyzeMediaExtractionSanitizer.js.map

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

package/dist/tools/AnalyzeMediaInputResolver.d.ts

@@ -0,0 +1,250 @@
+/**
+ * ANALYZE MEDIA INPUT RESOLVER
+ *
+ * Turns validated `path`/`paths` arguments into local files ready for
+ * upload: URL inputs are materialized through bounded streaming downloads,
+ * every input is readability-checked, and its effective upload content type
+ * is resolved.
+ *
+ * Content-type rule: the server-reported content type is authoritative and
+ * always wins over the extension-derived guess, so `image/webp` served from
+ * `/a.png` can never degrade to `image/png`; the generic
+ * `application/octet-stream` never wins.
+ *
+ * @module tools/AnalyzeMediaInputResolver
+ */
+import { MediaUrlFetcher, type MediaUrlFetchResult } from "../shared/mediaUrlFetcher.js";
+import { type AnalyzeMediaToolParams } from "./AnalyzeMediaContract.js";
+/**
+ * One media input resolved to a local file ready for upload.
+ */
+export interface ResolvedMediaInput {
+    /**
+     * Local filesystem path (already materialized for URL inputs).
+     */
+    readonly localPath: string;
+    /**
+     * Upload file name.
+     */
+    readonly filename: string;
+    /**
+     * File size in bytes.
+     */
+    readonly sizeBytes: number;
+    /**
+     * Effective MIME type for the upload session.
+     */
+    readonly contentType: string;
+    /**
+     * Server-reported content type for downloaded URLs.
+     */
+    readonly urlContentType?: string;
+    /**
+     * True when the download file extension was synthesized from the server
+     * content type.
+     */
+    readonly extensionSynthesized: boolean;
+    /**
+     * File identity staged at resolve time (`ino:size:mtime:birthtime:nlink`).
+     *
+     * @remarks
+     * The uploader compares it against the `fstat` identity of the opened
+     * handle so a same-size replacement between resolve and upload fails
+     * loudly instead of shipping the wrong bytes.
+     */
+    readonly stagedIdentity?: string;
+}
+/**
+ * Resolved inputs plus the owned URL downloads awaiting cleanup.
+ */
+export interface ResolvedMediaInputs {
+    /**
+     * Upload-ready inputs in request order.
+     */
+    readonly inputs: readonly ResolvedMediaInput[];
+    /**
+     * Owned URL downloads; the caller must clean each one up.
+     */
+    readonly materialized: readonly MediaUrlFetchResult[];
+    /**
+     * Single remote URL for server-side `source_url` ingest, set only when a
+     * lone http(s) input exceeds the 64 MiB client download cap. The fetcher
+     * SSRF guards already passed, so the server can ingest it directly
+     * without a client download + re-upload round trip.
+     */
+    readonly remoteUrl?: string;
+}
+/**
+ * Resolves validated media arguments into upload-ready local files.
+ */
+export declare class AnalyzeMediaInputResolver {
+    /**
+     * Do-not-follow flag for strict-mode opens (`0` where advisory).
+     *
+     * @remarks
+     * `O_NOFOLLOW` is honored on POSIX; on Windows it is advisory at best,
+     * so the `dev:ino` handle-identity comparison stays the real gate there.
+     */
+    private static readonly NO_FOLLOW_FLAG;
+    /**
+     * Bounded http(s) media fetcher used for URL inputs.
+     */
+    private readonly urlFetcher;
+    /**
+     * Creates a new {@link AnalyzeMediaInputResolver}.
+     *
+     * @param urlFetcher - URL fetcher used to materialize http(s) inputs.
+     */
+    constructor(urlFetcher: MediaUrlFetcher);
+    /**
+     * Resolves validated params into local upload-ready inputs.
+     *
+     * @remarks
+     * When `paths` carries at least one entry it wins over `path` (documented
+     * in the tool schema).
+     *
+     * @param params - Validated tool parameters.
+     * @param signal - Optional cancellation signal forwarded to URL downloads.
+     * @returns Resolved inputs plus owned downloads awaiting cleanup.
+     * @throws Error with an Spanish-first bilingual message when no input was provided, a download fails, or a file is unreadable.
+     */
+    resolve(params: AnalyzeMediaToolParams, signal?: AbortSignal): Promise<ResolvedMediaInputs>;
+    /**
+     * Fails fast when resolved bytes already exceed the upload ceiling.
+     *
+     * @remarks
+     * Multi-entry sets travel as one tar archive (headers, padding, manifest,
+     * end marker), so the fail-fast estimates the tar framing overhead (see
+     * {@link estimateMediaSetTarBytes}) instead of the raw byte sum: a set
+     * summing to 3.99 GiB raw would otherwise materialize ~100 temp downloads
+     * only for the packager to reject it once framing pushes it over 4 GiB.
+     * Over-estimating is correct for a fail-fast.
+     *
+     * @param resolvedBytes - Running total of resolved input bytes.
+     * @param entryCount - Resolved entries so far (including the latest).
+     * @param isImageSet - Whether the call resolves a multi-entry set.
+     * @throws Error with an Spanish-first bilingual message when the set already exceeds 4 GiB.
+     */
+    private throwOnUploadCeilingExceeded;
+    /**
+     * Resolves one local file into an upload-ready input.
+     *
+     * @param localPath - Absolute local file path.
+     * @returns Upload-ready input.
+     * @throws Error with an Spanish-first bilingual message when the file is missing or unreadable.
+     */
+    private resolveLocalFile;
+    /**
+     * Rejects a non-image entry of a multi-entry set right after it materializes.
+     *
+     * @remarks
+     * The tar packager repeats this check authoritatively before packing; the
+     * early check here only stops the resolver from downloading the rest of
+     * the set after the first failure. Single inputs keep any allowed type.
+     *
+     * @param localPath - Materialized local path (for error messages).
+     * @param contentType - Effective content type of the entry.
+     * @param isImageSet - Whether the call resolves a multi-entry set.
+     * @throws Error with an Spanish-first bilingual message when a set entry is not an image.
+     */
+    private throwOnNonImageSetEntry;
+    /**
+     * Resolves one downloaded URL file into an upload-ready input.
+     *
+     * @param fetched - Owned download result.
+     * @returns Upload-ready input preferring the server content type when the extension was synthesized.
+     * @throws Error with an Spanish-first bilingual message when the downloaded file is unreadable.
+     */
+    private resolveDownloadedFile;
+    /**
+     * Resolves the upload content type for one media input.
+     *
+     * @remarks
+     * The server-reported content type is authoritative: whenever it differs
+     * from the extension-derived guess it wins (a synthesized download
+     * extension is only a filesystem hint, and a mismatched authored
+     * extension such as `/a.png` serving `image/webp` must never shadow the
+     * real type). The generic `application/octet-stream` never wins.
+     *
+     * @param localPath - Local file path (already materialized for URLs).
+     * @param urlContentType - Server-reported content type for downloaded URLs.
+     * @returns Effective MIME type.
+     */
+    private resolveEffectiveContentType;
+    /**
+     * Detects a MIME type using the file extension.
+     *
+     * @param filePath - File path.
+     * @returns MIME type string.
+     */
+    private detectMimeType;
+    /**
+     * Validates that a path exists and is a readable file.
+     *
+     * @remarks
+     * `path` follows symlinks by design (the MCP host trusts the model with
+     * host-file access, like the documented DNS-rebinding residual in
+     * `mediaUrlFetcher.ts`). Operators that need strict mode set
+     * `ENRIVISION_DENY_SYMLINKS=1` to reject symlinked inputs with a Spanish
+     * error instead.
+     *
+     * @param filePath - Local filesystem path.
+     * @returns File size in bytes.
+     * @throws Error with an Spanish-first bilingual message when the file is missing, not readable, a rejected symlink, or exceeds 4 GiB.
+     */
+    private assertReadableFile;
+    /**
+     * Validates one file without ever trusting a path re-stat.
+     *
+     * @remarks
+     * `lstat` + `stat` + `open` on the same path races: a symlink swapped in
+     * between the check and the open defeats `ENRIVISION_DENY_SYMLINKS`.
+     * Opening with `O_NOFOLLOW` (POSIX) makes a swapped-in symlink fail with
+     * `ELOOP` instead, and the size/kind verdicts come from `fstat` on the
+     * opened handle — never from a second path lookup. The `dev:ino`
+     * comparison additionally rejects a real file swapped between `lstat`
+     * and `open` on platforms where `O_NOFOLLOW` is advisory.
+     *
+     * @param filePath - Local filesystem path.
+     * @returns File size in bytes plus the staged `fstat` identity.
+     * @throws Error with an Spanish-first bilingual message when the file is missing, a symlink, swapped mid-check, or exceeds 4 GiB.
+     */
+    private assertReadableFileWithoutSymlinks;
+    /**
+     * Applies the shared size/kind verdicts to one stat result.
+     *
+     * @param filePath - Local filesystem path (for error messages).
+     * @param size - File size in bytes.
+     * @param isFile - Whether the stat target is a regular file.
+     * @returns File size in bytes.
+     * @throws Error with an Spanish-first bilingual message when the target is not a file, is empty, or exceeds 4 GiB.
+     */
+    private checkFileStat;
+    /**
+     * Maps filesystem lookup failures to the stable not-found error.
+     *
+     * @param filePath - Local filesystem path (for error messages).
+     * @param error - Raw filesystem error.
+     * @throws Error with an Spanish-first bilingual message when the file is missing; rethrows unreadable-file errors otherwise.
+     */
+    private throwOnMissingFile;
+}
+/**
+ * Estimates the tar archive size for a multi-image set before packing.
+ *
+ * @remarks
+ * Fail-fast estimator (over-estimates on purpose): raw bytes plus one 512 B
+ * header per file, the manifest entry (512 B header plus content padded to
+ * 512 B), worst-case content padding (511 B per file), and the 1024 B end
+ * marker. The manifest term budgets 256 B of envelope plus 512 B per entry
+ * (worst case: 255 B basenames plus content type plus JSON overhead), so
+ * long filenames never under-estimate. Used by the resolver so a set that
+ * only fits raw never pays ~100 temp downloads before the packager rejects
+ * it.
+ *
+ * @param rawBytes - Summed input bytes.
+ * @param fileCount - Number of files in the set.
+ * @returns Estimated tar size in bytes.
+ */
+export declare function estimateMediaSetTarBytes(rawBytes: number, fileCount: number): number;
+//# sourceMappingURL=AnalyzeMediaInputResolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AnalyzeMediaInputResolver.d.ts","sourceRoot":"","sources":["../../src/tools/AnalyzeMediaInputResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,OAAO,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAEzF,OAAO,EAAwB,KAAK,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAa9F;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;IAEvC;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAEtD;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,yBAAyB;IACpC;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CACoB;IAE1D;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAE7C;;;;OAIG;gBACgB,UAAU,EAAE,eAAe;IAI9C;;;;;;;;;;;OAWG;IACU,OAAO,CAClB,MAAM,EAAE,sBAAsB,EAC9B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,mBAAmB,CAAC;IAyE/B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,4BAA4B;IAapC;;;;;;OAMG;YACW,gBAAgB;IAqB9B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,uBAAuB;IAQ/B;;;;;;OAMG;YACW,qBAAqB;IAwBnC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,2BAA2B;IASnC;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAQtB;;;;;;;;;;;;;OAaG;YACW,kBAAkB;IA4BhC;;;;;;;;;;;;;;;OAeG;YACW,iCAAiC;IAmC/C;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAerB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;CAS3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAWpF"}