pompelmi 0.35.5 → 1.1.0

package/dist/types/presets.d.ts

@@ -1,72 +0,0 @@
-import type { AnalysisDepth, ScanFn, Scanner, Verdict } from "./types";
-export type PresetName = "basic" | "advanced" | "malware-analysis" | "decompilation-basic" | "decompilation-deep" | string;
-export interface PresetOptions {
-    yaraRules?: string | string[];
-    yaraTimeout?: number;
-    enableDecompilation?: boolean;
-    decompilationEngine?: "binaryninja-hlil" | "ghidra-pcode" | "both";
-    decompilationDepth?: AnalysisDepth;
-    decompilationTimeout?: number;
-    binaryNinjaPath?: string;
-    pythonPath?: string;
-    ghidraPath?: string;
-    analyzeHeadless?: string;
-    timeout?: number;
-    [key: string]: unknown;
-}
-/**
- * A named scanner entry used with the array form of `composeScanners`.
- * The first element is a display name for the scanner (used when
- * `tagSourceName: true`), and the second element is the scanner itself.
- *
- * @example
- * const entry: NamedScanner = ['zipGuard', createZipBombGuard({ ... })];
- */
-export type NamedScanner = [name: string, scanner: Scanner];
-/**
- * Options for `composeScanners` when using the named-scanner array form.
- */
-export interface ComposeScannerOptions {
-    /**
-     * When `true` scanners run concurrently (Promise.all).
-     * When `false` (default) they run sequentially in order.
-     */
-    parallel?: boolean;
-    /**
-     * Stop scanning as soon as a match at this severity level (or higher) is
-     * found.  Severity order: `'malicious'` > `'suspicious'` > `'clean'`.
-     * Only effective when `parallel` is `false`.
-     */
-    stopOn?: Verdict;
-    /** Maximum time in milliseconds to wait for each individual scanner. */
-    timeoutMsPerScanner?: number;
-    /**
-     * When `true`, each match is tagged with the scanner's display name via
-     * `match.meta._sourceName`.  Useful for tracing which scanner produced a
-     * given result.
-     */
-    tagSourceName?: boolean;
-}
-/**
- * Compose multiple scanners into a single scanner.
- *
- * **Named-scanner array form** (recommended — matches the README examples):
- * ```ts
- * const scanner = composeScanners(
- *   [
- *     ['zipGuard', createZipBombGuard({ maxEntries: 512, maxCompressionRatio: 12 })],
- *     ['heuristics', CommonHeuristicsScanner],
- *   ],
- *   { parallel: false, stopOn: 'malicious', timeoutMsPerScanner: 5000, tagSourceName: true }
- * );
- * ```
- *
- * **Variadic form** (backward-compatible):
- * ```ts
- * const scanner = composeScanners(scannerA, scannerB, scannerC);
- * ```
- */
-export declare function composeScanners(namedScanners: NamedScanner[], opts?: ComposeScannerOptions): ScanFn;
-export declare function composeScanners(...scanners: Scanner[]): ScanFn;
-export declare function createPresetScanner(preset: PresetName, opts?: PresetOptions): Scanner;
-export declare const PRESET_CONFIGS: Record<string, PresetOptions>;

package/dist/types/quarantine/index.d.ts

@@ -1,18 +0,0 @@
-/**
- * Pompelmi Quarantine Module
- *
- * Provides a first-class quarantine workflow for secure upload pipelines:
- *   scan → flag → quarantine → review → promote | delete
- *
- * Entry points:
- *   import { QuarantineManager, FilesystemQuarantineStorage } from 'pompelmi/quarantine';
- *
- * The storage layer is pluggable via the `QuarantineStorage` interface.
- * `FilesystemQuarantineStorage` is the reference implementation for local/on-premise use.
- *
- * This module is Node.js-only (uses fs/crypto/path).
- * It is NOT included in the 'pompelmi/browser' or 'pompelmi/react' bundles.
- */
-export { FilesystemQuarantineStorage, type FilesystemQuarantineStorageOptions, type QuarantineStorage, } from "./storage";
-export type { QuarantineDecision, QuarantinedFileInfo, QuarantineEntry, QuarantineFilter, QuarantineReport, QuarantineReview, QuarantineStatus, } from "./types";
-export { QuarantineManager, type QuarantineManagerOptions } from "./workflow";

package/dist/types/quarantine/storage.d.ts

@@ -1,77 +0,0 @@
-/**
- * Quarantine storage adapter interface and filesystem reference implementation.
- *
- * The `QuarantineStorage` interface decouples the quarantine workflow from any
- * specific persistence layer.  You can implement it for S3, GCS, a database,
- * or any other backend.
- *
- * The built-in `FilesystemQuarantineStorage` stores files and metadata as JSON
- * in a local directory — suitable for development, self-hosted, and on-premise
- * deployments where data must not leave the machine.
- *
- * @module quarantine/storage
- */
-import type { QuarantineEntry, QuarantineFilter } from "./types";
-/**
- * Storage adapter for the quarantine workflow.
- * Implement this interface to support any backend (S3, GCS, DB, etc.).
- */
-export interface QuarantineStorage {
-    /**
-     * Persist the raw bytes of a quarantined file.
-     * Returns a `storageKey` that can later be used to retrieve or delete the bytes.
-     */
-    saveFile(id: string, bytes: Uint8Array): Promise<string>;
-    /**
-     * Retrieve the raw bytes of a quarantined file.
-     * Returns `null` if the file is not found.
-     */
-    getFile(storageKey: string): Promise<Uint8Array | null>;
-    /**
-     * Permanently remove the raw bytes of a quarantined file.
-     * No-op if already removed.
-     */
-    deleteFile(storageKey: string): Promise<void>;
-    /** Persist a quarantine entry (metadata + scan report). */
-    saveEntry(entry: QuarantineEntry): Promise<void>;
-    /** Load a quarantine entry by id. Returns `null` if not found. */
-    getEntry(id: string): Promise<QuarantineEntry | null>;
-    /** Update an existing quarantine entry (partial update). */
-    updateEntry(id: string, patch: Partial<QuarantineEntry>): Promise<QuarantineEntry>;
-    /** List quarantine entries matching the given filter. */
-    listEntries(filter?: QuarantineFilter): Promise<QuarantineEntry[]>;
-    /** Return the total count of quarantine entries matching the filter. */
-    countEntries(filter?: QuarantineFilter): Promise<number>;
-}
-export interface FilesystemQuarantineStorageOptions {
-    /**
-     * Root directory for quarantine storage.
-     * Two subdirectories are created: `files/` (raw bytes) and `meta/` (JSON).
-     */
-    dir: string;
-    /** Create the directory if it does not exist (default: true). */
-    createIfMissing?: boolean;
-}
-/**
- * Reference implementation of `QuarantineStorage` backed by the local filesystem.
- *
- * File layout:
- *   <dir>/files/<storageKey>   — raw file bytes
- *   <dir>/meta/<id>.json       — QuarantineEntry JSON
- *
- * Suitable for single-process servers.  For multi-process or distributed
- * deployments, implement `QuarantineStorage` against a shared backend.
- */
-export declare class FilesystemQuarantineStorage implements QuarantineStorage {
-    private readonly filesDir;
-    private readonly metaDir;
-    constructor(options: FilesystemQuarantineStorageOptions);
-    saveFile(id: string, bytes: Uint8Array): Promise<string>;
-    getFile(storageKey: string): Promise<Uint8Array | null>;
-    deleteFile(storageKey: string): Promise<void>;
-    saveEntry(entry: QuarantineEntry): Promise<void>;
-    getEntry(id: string): Promise<QuarantineEntry | null>;
-    updateEntry(id: string, patch: Partial<QuarantineEntry>): Promise<QuarantineEntry>;
-    listEntries(filter?: QuarantineFilter): Promise<QuarantineEntry[]>;
-    countEntries(filter?: QuarantineFilter): Promise<number>;
-}

package/dist/types/quarantine/types.d.ts

@@ -1,78 +0,0 @@
-/**
- * Quarantine system types for Pompelmi.
- *
- * A quarantine entry represents a file that was flagged during scanning and is
- * held for manual review before being accepted or permanently removed.
- *
- * The lifecycle of a quarantined entry:
- *
- *   scan → flagged → quarantined → reviewed → promoted | deleted
- *
- * @module quarantine/types
- */
-import type { ScanReport } from "../types";
-/** The review status of a quarantined file. */
-export type QuarantineStatus = "pending" | "reviewing" | "promoted" | "deleted";
-/** Immutable metadata about the file at upload time. */
-export interface QuarantinedFileInfo {
-    /** Original filename supplied by the uploader. */
-    originalName: string;
-    /** Detected MIME type (from magic bytes, not the Content-Type header). */
-    mimeType?: string;
-    /** File size in bytes. */
-    sizeBytes: number;
-    /** SHA-256 hex digest of the file content. */
-    sha256: string;
-    /** Uploader identity — opaque string (user id, session id, IP, etc.). */
-    uploadedBy?: string;
-}
-/** A quarantine entry created when a file is flagged. */
-export interface QuarantineEntry {
-    /** Stable identifier for this quarantine entry (UUID). */
-    id: string;
-    /** Filename used to locate the quarantined bytes in storage. */
-    storageKey: string;
-    /** Metadata captured at upload time. */
-    file: QuarantinedFileInfo;
-    /** The scan report that triggered quarantine. */
-    scanReport: ScanReport;
-    /** ISO-8601 timestamp when the file was quarantined. */
-    quarantinedAt: string;
-    /** Current review status. */
-    status: QuarantineStatus;
-    /** ISO-8601 timestamp of the last status change. */
-    updatedAt: string;
-    /** Identity of the reviewer (operator id, etc.). Populated at review time. */
-    reviewedBy?: string;
-    /** Free-text review note from the operator. */
-    reviewNote?: string;
-    /** ISO-8601 timestamp when the final decision (promote/delete) was made. */
-    resolvedAt?: string;
-    /** Optional application-specific tags or labels. */
-    tags?: string[];
-}
-/** The outcome of a manual review. */
-export type QuarantineDecision = "promote" | "delete";
-/** Input required to resolve a quarantine entry. */
-export interface QuarantineReview {
-    decision: QuarantineDecision;
-    reviewedBy?: string;
-    reviewNote?: string;
-}
-/** A structured JSON report of all quarantined entries (for audit/export). */
-export interface QuarantineReport {
-    generatedAt: string;
-    totalEntries: number;
-    byStatus: Record<QuarantineStatus, number>;
-    entries: QuarantineEntry[];
-}
-/** Filter parameters for listing quarantine entries. */
-export interface QuarantineFilter {
-    status?: QuarantineStatus | QuarantineStatus[];
-    /** Return only entries quarantined after this ISO-8601 timestamp. */
-    after?: string;
-    /** Return only entries quarantined before this ISO-8601 timestamp. */
-    before?: string;
-    /** Maximum number of results to return. */
-    limit?: number;
-}

package/dist/types/quarantine/workflow.d.ts

@@ -1,97 +0,0 @@
-/**
- * Quarantine workflow — core API for the quarantine/review/resolve lifecycle.
- *
- * Usage (Node.js):
- *
- * ```ts
- * import { scanBytes } from 'pompelmi';
- * import { QuarantineManager, FilesystemQuarantineStorage } from 'pompelmi/quarantine';
- *
- * const quarantine = new QuarantineManager({
- *   storage: new FilesystemQuarantineStorage({ dir: './quarantine' }),
- * });
- *
- * const report = await scanBytes(fileBytes, { ctx: { filename: file.name } });
- *
- * if (report.verdict !== 'clean') {
- *   const entry = await quarantine.quarantine(fileBytes, report, {
- *     originalName: file.name,
- *     sizeBytes: fileBytes.length,
- *     uploadedBy: req.user?.id,
- *   });
- *   console.log('Quarantined:', entry.id);
- * }
- * ```
- *
- * @module quarantine/workflow
- */
-import type { ScanReport } from "../types";
-import type { QuarantineStorage } from "./storage";
-import type { QuarantinedFileInfo, QuarantineEntry, QuarantineFilter, QuarantineReport, QuarantineReview } from "./types";
-export interface QuarantineManagerOptions {
-    /** Storage adapter — use `FilesystemQuarantineStorage` for local deployments. */
-    storage: QuarantineStorage;
-    /**
-     * If true, files with a 'suspicious' verdict are also quarantined.
-     * Default: true.
-     */
-    quarantineSuspicious?: boolean;
-    /**
-     * If true, files with a 'malicious' verdict are also quarantined.
-     * Default: true.
-     */
-    quarantineMalicious?: boolean;
-}
-/**
- * Manages the full lifecycle of quarantined files:
- *   scan → quarantine → review → promote | delete
- */
-export declare class QuarantineManager {
-    private readonly storage;
-    private readonly quarantineSuspicious;
-    private readonly quarantineMalicious;
-    constructor(options: QuarantineManagerOptions);
-    /**
-     * Determine whether a scan report should trigger quarantine per the
-     * configured policy.
-     */
-    shouldQuarantine(report: ScanReport): boolean;
-    /**
-     * Quarantine a file: save the bytes in storage, create the metadata entry,
-     * and return the entry.
-     *
-     * @param bytes     Raw file bytes.
-     * @param report    The scan report that triggered quarantine.
-     * @param fileInfo  Partial metadata; `sha256` is derived from `bytes` if omitted.
-     */
-    quarantine(bytes: Uint8Array, report: ScanReport, fileInfo: Omit<QuarantinedFileInfo, "sha256"> & {
-        sha256?: string;
-    }): Promise<QuarantineEntry>;
-    /**
-     * Mark an entry as being actively reviewed.
-     */
-    startReview(id: string, reviewedBy?: string): Promise<QuarantineEntry>;
-    /**
-     * Resolve a quarantine entry with a final decision.
-     *
-     * - `promote`: the file is cleared — bytes remain in storage for the caller
-     *   to move to its final destination.
-     * - `delete`: the bytes are permanently removed from quarantine storage.
-     */
-    resolve(id: string, review: QuarantineReview): Promise<QuarantineEntry>;
-    /**
-     * Retrieve the raw bytes of a promoted file so the caller can move it to
-     * permanent storage.  Returns `null` if the entry is not found or has been
-     * deleted.
-     */
-    getFile(id: string): Promise<Uint8Array | null>;
-    getEntry(id: string): Promise<QuarantineEntry | null>;
-    listEntries(filter?: QuarantineFilter): Promise<QuarantineEntry[]>;
-    listPending(): Promise<QuarantineEntry[]>;
-    countEntries(filter?: QuarantineFilter): Promise<number>;
-    /**
-     * Generate a structured JSON report of all quarantine entries matching the
-     * filter — suitable for audit logs and dashboards.
-     */
-    report(filter?: QuarantineFilter): Promise<QuarantineReport>;
-}

package/dist/types/react-index.d.ts

@@ -1,13 +0,0 @@
-/**
- * src/react-index.ts — React entry point for Pompelmi.
- *
- * Re-exports the full browser-safe Pompelmi API plus the React hook.
- * Import from 'pompelmi/react'.
- *
- * Peer dependency: react ^18 || ^19
- *
- * @example
- * import { useFileScanner } from 'pompelmi/react';
- */
-export * from "./browser-index";
-export { useFileScanner } from "./useFileScanner";

package/dist/types/risk.d.ts

@@ -1,18 +0,0 @@
-export type Severity = "clean" | "suspicious" | "malicious";
-export type Match = {
-    rule: string;
-    meta?: Record<string, any>;
-};
-export type Verdict = {
-    severity: Severity;
-    reasons: string[];
-    matches: Match[];
-    mime?: string;
-};
-export type Policy = {
-    includeExtensions: string[];
-    allowedMimeTypes: string[];
-    maxFileSizeBytes: number;
-    denyScriptableSvg?: boolean;
-};
-export declare function prefilter(bytes: Uint8Array, origName: string, policy: Policy): Verdict;

package/dist/types/scan/remote.d.ts

@@ -1,12 +0,0 @@
-import type { YaraMatch } from "../yara/index";
-import type { RemoteEngineOptions } from "../yara/remote";
-export interface RemoteScanResult {
-    file: File;
-    matches: YaraMatch[];
-    error?: string;
-}
-/**
- * Scansiona una lista di File nel browser usando il motore remoto via HTTP.
- * Non richiede WASM né dipendenze native sul client.
- */
-export declare function scanFilesWithRemoteYara(files: File[], rulesSource: string, remote: RemoteEngineOptions): Promise<RemoteScanResult[]>;

package/dist/types/scan.d.ts

@@ -1,17 +0,0 @@
-import type { ScannerConfig } from "./config";
-import { type PresetName } from "./presets";
-import type { ScanContext, ScanReport } from "./types";
-export type ScanOptions = {
-    preset?: PresetName;
-    ctx?: ScanContext;
-    enableAdvancedDetection?: boolean;
-    enablePerformanceTracking?: boolean;
-    enableCache?: boolean;
-    config?: Partial<ScannerConfig>;
-};
-/** Scan di bytes (browser/node) usando preset (default: zip-basic) */
-export declare function scanBytes(input: Uint8Array, opts?: ScanOptions): Promise<ScanReport>;
-/** Scan di un file su disco (Node). Import dinamico per non vincolare il bundle browser. */
-export declare function scanFile(filePath: string, opts?: Omit<ScanOptions, "ctx">): Promise<ScanReport>;
-/** Scan multipli File (browser) usando scanBytes + preset di default */
-export declare function scanFiles(files: ArrayLike<File>, opts?: Omit<ScanOptions, "ctx">): Promise<ScanReport[]>;

package/dist/types/scanners/common-heuristics.d.ts

@@ -1,14 +0,0 @@
-/**
- * CommonHeuristicsScanner
- * Lightweight, no-deps heuristics for common risky file patterns.
- * Returns matches as [{ rule, severity?, meta? }].
- */
-export type HeuristicMatch = {
-    rule: string;
-    severity?: "info" | "low" | "medium" | "high" | "critical" | "suspicious" | "malicious";
-    meta?: Record<string, unknown>;
-};
-export interface SimpleScanner {
-    scan(bytes: Uint8Array): Promise<HeuristicMatch[]>;
-}
-export declare const CommonHeuristicsScanner: SimpleScanner;

package/dist/types/scanners/zip-bomb-guard.d.ts

@@ -1,9 +0,0 @@
-import type { Scanner } from "../types";
-export type ZipBombGuardOptions = {
-    maxEntries?: number;
-    maxTotalUncompressedBytes?: number;
-    maxEntryNameLength?: number;
-    maxCompressionRatio?: number;
-    eocdSearchWindow?: number;
-};
-export declare function createZipBombGuard(opts?: ZipBombGuardOptions): Scanner;

package/dist/types/scanners/zipTraversalGuard.d.ts

@@ -1,19 +0,0 @@
-/**
- * createZipTraversalGuard – guards against path traversal & header spoofing in ZIPs.
- * EXPECTS: caller provides an iterator over entries with metadata (name, isSymlink, target?, from CEN & LFH).
- * Return non-empty array to flag.
- */
-export type EntryMeta = {
-    nameCEN: string;
-    nameLFH: string;
-    isSymlink?: boolean;
-    linkTarget?: string;
-};
-export declare function createZipTraversalGuard(): {
-    id: string;
-    scan(entries: AsyncIterable<EntryMeta>): Promise<{
-        rule: string;
-        severity: "suspicious";
-        msg: string;
-    }[]>;
-};

package/dist/types/src/audit.d.ts

@@ -1,84 +0,0 @@
-/**
- * Audit trail for Pompelmi scan and quarantine events.
- *
- * Produces structured, append-only audit records suitable for:
- *   - compliance logging (HIPAA, SOC 2, ISO 27001)
- *   - SIEM ingestion
- *   - operational dashboards
- *   - incident response
- *
- * Usage:
- * ```ts
- * import { AuditTrail } from 'pompelmi/audit';
- *
- * const audit = new AuditTrail({ dest: 'file', path: './audit.jsonl' });
- * audit.logScanComplete({ filename: 'upload.zip', verdict: 'suspicious', ... });
- * audit.logQuarantine({ entryId: '...', sha256: '...', ... });
- * ```
- *
- * @module audit
- */
-import type { QuarantineEntry } from "./quarantine/types";
-import type { ScanReport } from "./types";
-export type AuditEventType = "scan.complete" | "scan.error" | "threat.detected" | "quarantine.created" | "quarantine.resolved" | "quarantine.deleted";
-interface BaseAuditRecord {
-    /** ISO-8601 timestamp. */
-    timestamp: string;
-    /** Event type for structured log routing. */
-    event: AuditEventType;
-    /** Application-assigned session or request id for correlation. */
-    correlationId?: string;
-    /** Uploader identity. */
-    uploadedBy?: string;
-}
-export interface ScanAuditRecord extends BaseAuditRecord {
-    event: "scan.complete" | "scan.error" | "threat.detected";
-    filename?: string;
-    mimeType?: string;
-    sizeBytes?: number;
-    sha256?: string;
-    verdict: ScanReport["verdict"];
-    matchCount: number;
-    durationMs?: number;
-    engine?: string;
-    error?: string;
-}
-export interface QuarantineAuditRecord extends BaseAuditRecord {
-    event: "quarantine.created" | "quarantine.resolved" | "quarantine.deleted";
-    quarantineId: string;
-    filename?: string;
-    sha256: string;
-    decision?: "promote" | "delete";
-    reviewedBy?: string;
-    reviewNote?: string;
-}
-export type AuditRecord = ScanAuditRecord | QuarantineAuditRecord;
-export type AuditDest = {
-    dest: "console";
-} | {
-    dest: "file";
-    path: string;
-} | {
-    dest: "custom";
-    write: (record: AuditRecord) => void | Promise<void>;
-};
-export interface AuditTrailOptions {
-    /** Where to write audit records. Default: 'console'. */
-    output?: AuditDest;
-    /** If true, pretty-print JSON. Useful for debugging. Default: false. */
-    pretty?: boolean;
-}
-export declare class AuditTrail {
-    private readonly options;
-    constructor(options?: AuditTrailOptions);
-    /** Log a completed scan. */
-    logScanComplete(report: ScanReport, extra?: Pick<ScanAuditRecord, "filename" | "sizeBytes" | "sha256" | "correlationId" | "uploadedBy">): void;
-    /** Log a scan error. */
-    logScanError(error: unknown, extra?: Pick<ScanAuditRecord, "filename" | "correlationId" | "uploadedBy">): void;
-    /** Log a new quarantine entry. */
-    logQuarantine(entry: QuarantineEntry, correlationId?: string): void;
-    /** Log a quarantine resolution (promote or delete). */
-    logQuarantineResolved(entry: QuarantineEntry, correlationId?: string): void;
-    private write;
-}
-export {};

package/dist/types/src/browser-index.d.ts

@@ -1,29 +0,0 @@
-/**
- * src/browser-index.ts — Browser-safe entry point for Pompelmi.
- *
- * This bundle contains ONLY modules that are safe to use in a browser/bundler
- * environment. It does NOT include:
- *  - HIPAA compliance module (uses Node.js crypto/os/path)
- *  - Cache manager (uses Node.js crypto for content hashing)
- *  - Threat intelligence (uses Node.js crypto)
- *  - ZIP streaming (uses unzipper, a Node.js stream library)
- *  - YARA native bindings
- *  - Batch scanner (Node.js-optimised concurrency)
- *
- * For the full Node.js API (all of the above included), import from 'pompelmi'
- * or 'pompelmi/node'.
- *
- * For the React hook, import from 'pompelmi/react'.
- */
-export { DEFAULT_POLICY, definePolicy } from "./policy";
-export { ARCHIVES, CONSERVATIVE_DEFAULT, DOCUMENTS_ONLY, getPolicyPack, IMAGES_ONLY, POLICY_PACKS, type PolicyPackName, STRICT_PUBLIC_UPLOAD, } from "./policy-packs";
-export { type ComposeScannerOptions, composeScanners, createPresetScanner, type NamedScanner, type PresetName, type PresetOptions, } from "./presets";
-export { type ScanOptions, scanBytes, scanFile, scanFiles } from "./scan";
-export { CommonHeuristicsScanner } from "./scanners/common-heuristics";
-export { createZipBombGuard } from "./scanners/zip-bomb-guard";
-export type { FileInfo, Match, ScanContext, ScanFn, Scanner, ScanReport, Uint8ArrayLike, Verdict, YaraMatch, } from "./types";
-export { analyzeNestedArchives, detectObfuscatedScripts, detectPolyglot, } from "./utils/advanced-detection";
-export { type ExportFormat, type ExportOptions, exportScanResults, ScanResultExporter, } from "./utils/export";
-export { aggregateScanStats, type PerformanceMetrics, PerformanceTracker, type ScanStatistics, } from "./utils/performance-metrics";
-export { validateFile } from "./validate";
-export { mapMatchesToVerdict } from "./verdict";