pompelmi 0.31.0 → 0.32.1

package/README.md

@@ -287,11 +287,17 @@ Get secure file scanning running in under 5 minutes with pompelmi's zero-config
 
 ### Step 1: Create Security Policy
 
-Create a reusable security policy and scanner configuration:
+Create a reusable security policy and scanner configuration.
+
+> **`composeScanners` API** — two supported forms:
+> - **Named-scanner array** *(recommended)*: `composeScanners([["name", scanner], ...], opts?)` — supports `parallel`, `stopOn`, `timeoutMsPerScanner`, and `tagSourceName` options.
+> - **Variadic** *(backward-compatible)*: `composeScanners(scannerA, scannerB, ...)` — runs scanners sequentially, no options.
 
 ```ts
 // lib/security.ts
 import { CommonHeuristicsScanner, createZipBombGuard, composeScanners } from 'pompelmi';
+// Optional: import types for explicit annotation
+// import type { NamedScanner, ComposeScannerOptions } from 'pompelmi';
 
 export const policy = {
   includeExtensions: ['zip', 'png', 'jpg', 'jpeg', 'pdf', 'txt'],

package/dist/pompelmi.cjs

@@ -28,7 +28,96 @@ var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 function toScanFn(s) {
     return (typeof s === "function" ? s : s.scan);
 }
-function composeScanners(...scanners) {
+/** Map a Match's severity field to a Verdict for stopOn comparison. */
+function matchToVerdict(m) {
+    const s = m.severity;
+    if (s === "critical" || s === "high" || s === "malicious")
+        return "malicious";
+    if (s === "medium" || s === "low" || s === "suspicious" || s === "info")
+        return "suspicious";
+    return "clean";
+}
+/** Highest verdict across all matches in the list. */
+function highestSeverity(matches) {
+    if (matches.length === 0)
+        return null;
+    if (matches.some((m) => matchToVerdict(m) === "malicious"))
+        return "malicious";
+    if (matches.some((m) => matchToVerdict(m) === "suspicious"))
+        return "suspicious";
+    return "clean";
+}
+const SEVERITY_RANK = { malicious: 2, suspicious: 1, clean: 0 };
+function shouldStop(matches, stopOn) {
+    if (!stopOn)
+        return false;
+    const highest = highestSeverity(matches);
+    if (!highest)
+        return false;
+    return SEVERITY_RANK[highest] >= SEVERITY_RANK[stopOn];
+}
+async function runWithTimeout(fn, timeoutMs) {
+    if (!timeoutMs)
+        return fn();
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("scanner timeout")), timeoutMs);
+        fn().then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+    });
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function composeScanners(...args) {
+    const first = args[0];
+    const rest = args.slice(1);
+    // ── Named-scanner array form ──────────────────────────────────────────────
+    if (Array.isArray(first) &&
+        (first.length === 0 || (Array.isArray(first[0]) && typeof first[0][0] === "string"))) {
+        const entries = first;
+        const opts = rest.length > 0 && !Array.isArray(rest[0]) && typeof rest[0] !== "function" &&
+            !(typeof rest[0] === "object" && rest[0] !== null && "scan" in rest[0])
+            ? rest[0]
+            : {};
+        return async (input, ctx) => {
+            const all = [];
+            if (opts.parallel) {
+                // Parallel execution — collect all results then return
+                const results = await Promise.allSettled(entries.map(([name, scanner]) => runWithTimeout(() => toScanFn(scanner)(input, ctx), opts.timeoutMsPerScanner)));
+                for (let i = 0; i < results.length; i++) {
+                    const result = results[i];
+                    if (result.status === "fulfilled" && Array.isArray(result.value)) {
+                        const matches = opts.tagSourceName
+                            ? result.value.map((m) => ({
+                                ...m,
+                                meta: { ...m.meta, _sourceName: entries[i][0] },
+                            }))
+                            : result.value;
+                        all.push(...matches);
+                    }
+                }
+            }
+            else {
+                // Sequential execution with optional stopOn short-circuit
+                for (const [name, scanner] of entries) {
+                    try {
+                        const out = await runWithTimeout(() => toScanFn(scanner)(input, ctx), opts.timeoutMsPerScanner);
+                        if (Array.isArray(out)) {
+                            const matches = opts.tagSourceName
+                                ? out.map((m) => ({ ...m, meta: { ...m.meta, _sourceName: name } }))
+                                : out;
+                            all.push(...matches);
+                            if (shouldStop(all, opts.stopOn))
+                                break;
+                        }
+                    }
+                    catch {
+                        // individual scanner failure is non-fatal
+                    }
+                }
+            }
+            return all;
+        };
+    }
+    // ── Variadic form (backward-compatible) ───────────────────────────────────
+    const scanners = [first, ...rest].filter(Boolean);
     return async (input, ctx) => {
         const all = [];
         for (const s of scanners) {