pompelmi 0.33.0 → 0.34.0

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

@@ -0,0 +1,18 @@
+/**
+ * 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 { QuarantineManager, type QuarantineManagerOptions } from './workflow';
+export { FilesystemQuarantineStorage, type QuarantineStorage, type FilesystemQuarantineStorageOptions, } from './storage';
+export type { QuarantineEntry, QuarantinedFileInfo, QuarantineStatus, QuarantineDecision, QuarantineReview, QuarantineReport, QuarantineFilter, } from './types';

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

@@ -0,0 +1,77 @@
+/**
+ * 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

@@ -0,0 +1,78 @@
+/**
+ * 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

@@ -0,0 +1,97 @@
+/**
+ * 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 { QuarantineEntry, QuarantineFilter, QuarantineReport, QuarantineReview, QuarantinedFileInfo } from './types';
+import type { QuarantineStorage } from './storage';
+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

@@ -0,0 +1,13 @@
+/**
+ * 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/types.d.ts

@@ -7,7 +7,6 @@ export interface YaraMatch {
     meta?: Record<string, unknown>;
 }
 export * from './types/decompilation';
-export * from './hipaa-compliance';
 export interface Match {
     rule: string;
     severity?: 'info' | 'low' | 'medium' | 'high' | 'critical' | 'suspicious' | 'malicious';

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "pompelmi",
-  "version": "0.33.0",
-  "description": "Fast, private malware scanner for Node.js file uploads. TypeScript-first library with Express, Koa, Fastify, Next.js & Nuxt/Nitro adapters. Features deep ZIP inspection, YARA integration, ZIP bomb protection, and real-time threat detection. Zero cloud dependencies - scan files in-process before they hit disk. Perfect for GDPR/HIPAA compliance.",
+  "version": "0.34.0",
+  "description": "Fast, private malware scanner for Node.js file uploads. TypeScript-first library with Express, Koa, Fastify, Next.js & Nuxt/Nitro adapters. Features deep ZIP inspection, YARA integration, ZIP bomb protection, and real-time threat detection. Zero cloud dependencies - scan files in-process before they hit disk. Works well for privacy-sensitive and regulated environments.",
   "main": "./dist/pompelmi.cjs",
   "module": "./dist/pompelmi.esm.js",
   "type": "module",
   "browser": {
     "yara": false,
-    "util": false
+    "util": false,
+    "crypto": false,
+    "os": false,
+    "path": false,
+    "unzipper": false,
+    "child_process": false
   },
   "repository": {
     "type": "git",
@@ -140,6 +145,10 @@
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "react-dom": { "optional": true }
+  },
   "optionalDependencies": {
     "@litko/yara-x": "^0.2.1"
   },
@@ -150,6 +159,48 @@
       "require": "./dist/pompelmi.cjs",
       "default": "./dist/pompelmi.esm.js"
     },
+    "./node": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/pompelmi.esm.js",
+      "require": "./dist/pompelmi.cjs",
+      "default": "./dist/pompelmi.esm.js"
+    },
+    "./browser": {
+      "types": "./dist/types/browser-index.d.ts",
+      "import": "./dist/pompelmi.browser.esm.js",
+      "require": "./dist/pompelmi.browser.cjs",
+      "default": "./dist/pompelmi.browser.esm.js"
+    },
+    "./react": {
+      "types": "./dist/types/react-index.d.ts",
+      "import": "./dist/pompelmi.react.esm.js",
+      "require": "./dist/pompelmi.react.cjs",
+      "default": "./dist/pompelmi.react.esm.js"
+    },
+    "./quarantine": {
+      "types": "./dist/types/quarantine/index.d.ts",
+      "import": "./dist/pompelmi.quarantine.esm.js",
+      "require": "./dist/pompelmi.quarantine.cjs",
+      "default": "./dist/pompelmi.quarantine.esm.js"
+    },
+    "./hooks": {
+      "types": "./dist/types/hooks.d.ts",
+      "import": "./dist/pompelmi.hooks.esm.js",
+      "require": "./dist/pompelmi.hooks.cjs",
+      "default": "./dist/pompelmi.hooks.esm.js"
+    },
+    "./audit": {
+      "types": "./dist/types/audit.d.ts",
+      "import": "./dist/pompelmi.audit.esm.js",
+      "require": "./dist/pompelmi.audit.cjs",
+      "default": "./dist/pompelmi.audit.esm.js"
+    },
+    "./policy-packs": {
+      "types": "./dist/types/policy-packs.d.ts",
+      "import": "./dist/pompelmi.policy-packs.esm.js",
+      "require": "./dist/pompelmi.policy-packs.cjs",
+      "default": "./dist/pompelmi.policy-packs.esm.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [