pompelmi 0.34.9 → 0.35.0

package/README.md

@@ -5,6 +5,7 @@
   <p>
     <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm version" src="https://img.shields.io/npm/v/pompelmi"></a>
     <a href="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/pompelmi/pompelmi/ci.yml?label=ci"></a>
+    <a href="https://codecov.io/gh/pompelmi/pompelmi"><img alt="Codecov" src="https://codecov.io/gh/pompelmi/pompelmi/branch/main/graph/badge.svg?flag=core"></a>
     <a href="https://github.com/pompelmi/pompelmi/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/pompelmi/pompelmi"></a>
     <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm downloads" src="https://img.shields.io/npm/dm/pompelmi"></a>
   </p>
@@ -93,16 +94,31 @@ if (report.verdict !== "clean") {
 }
 ```
 
-## Next steps
+## Start Here
 
-- [Documentation](https://pompelmi.github.io/pompelmi/)
+- Express: [Docs](https://pompelmi.github.io/pompelmi/how-to/express/) · [Examples](./examples/express-minimal)
+- Next.js: [Docs](https://pompelmi.github.io/pompelmi/how-to/nextjs/) · [Examples](./examples/next-app-router)
+- NestJS: [Docs](https://pompelmi.github.io/pompelmi/how-to/nestjs/) · [Example app](./examples/nestjs-app)
+- Fastify: [Docs](https://pompelmi.github.io/pompelmi/how-to/fastify/) · [Package](./packages/fastify-plugin)
+- Koa: [Docs](https://pompelmi.github.io/pompelmi/how-to/koa/) · [Package](./packages/koa-middleware)
+- CI/CD: [Use case](https://pompelmi.github.io/pompelmi/use-cases/cicd-artifact-scanning/) · [Blog](https://pompelmi.github.io/pompelmi/blog/cicd-scan-build-artifacts/)
+- S3 / object storage: [Tutorial](https://pompelmi.github.io/pompelmi/tutorials/secure-s3-presigned-uploads-with-malware-scanning/) · [Use case](https://pompelmi.github.io/pompelmi/use-cases/s3-presigned-upload-security/)
+
+## Go Deeper
+
+- [Docs home](https://pompelmi.github.io/pompelmi/)
+- [Use cases](https://pompelmi.github.io/pompelmi/use-cases/)
+- [Comparisons](https://pompelmi.github.io/pompelmi/comparisons/)
+- [Tutorials](https://pompelmi.github.io/pompelmi/tutorials/)
+- [Featured in](https://pompelmi.github.io/pompelmi/featured-in/)
+- [Translations](https://pompelmi.github.io/pompelmi/translations/)
 - [Examples index](./examples/README.md)
 - [Demo example](./examples/demo)
 - [Contributing](./CONTRIBUTING.md)
 - [Security](./SECURITY.md)
 - [Roadmap](./ROADMAP.md)
 
-## What Problem It Solves
+## What It Checks
 
 Upload endpoints are part of your attack surface. A renamed executable, a risky PDF, or a hostile archive can look harmless until it is stored, unpacked, served, or parsed by another system.
 
@@ -115,12 +131,6 @@ Pompelmi adds checks at the upload boundary for:
 
 The goal is simple: inspect first, store later.
 
-## Why This Shape
-
-- Plain Markdown, readable in GitHub and in a terminal
-- Fast path first: install, example, then deeper links
-- Minimal top-level detail, with docs and examples for everything else
-
 ## Ecosystem
 
 - `pompelmi`
@@ -138,7 +148,7 @@ The goal is simple: inspect first, store later.
 - `packages/` framework adapters and supporting packages
 - `examples/` runnable examples
 - `tests/` test coverage
-- `website/` documentation site
+- `website/` public docs, blog, and discovery site
 
 ## Development
 
@@ -150,16 +160,18 @@ pnpm build
 
 <!-- MENTIONS:START -->
 
-## 🌟 Featured In
+## Featured In
+
+Full page: [pompelmi.github.io/pompelmi/featured-in](https://pompelmi.github.io/pompelmi/featured-in/)
 
 *Last updated: March 20, 2026*
 
-### 📋 Awesome Lists & Curated Collections
+### Awesome Lists & Curated Collections
 
 - [Awesome JavaScript](https://github.com/sorrycc/awesome-javascript) — sorrycc
 - [Awesome TypeScript](https://github.com/dzharii/awesome-typescript) — dzharii
 
-### 📰 Newsletters & Roundups
+### Newsletters & Roundups
 
 - [The Overflow Issue 319: Dogfooding your SDLC](https://stackoverflow.blog/newsletter/issue-319-dogfooding-your-sdlc/) — Stack Overflow (2026-03-04)
 - [Hottest cybersecurity open-source tools of the month: February 2026](https://www.helpnetsecurity.com/2026/02/26/hottest-cybersecurity-open-source-tools-of-the-month-february-2026/) — Help Net Security (2026-02-26)
@@ -167,7 +179,7 @@ pnpm build
 - [Node Weekly Issue 594](https://nodeweekly.com/issues/594) — Node Weekly (2025-09-30)
 - [Det. Eng. Weekly Issue #124 - The DEFCON hangover is real](https://www.detectionengineering.net/p/det-eng-weekly-issue-124-the-defcon) — Detection Engineering (2025-08-13)
 
-### 🔗 Other Mentions
+### Other Mentions
 
 - [Defense against uploads: Q&A with OSS file scanner, pompelmi](https://stackoverflow.blog/2026/02/23/defense-against-uploads-oss-file-scanner-pompelmi/) — Stack Overflow (2026-02-23)
 - [Pompelmi: Open-source secure file upload scanning for Node.js](https://www.helpnetsecurity.com/2026/02/02/pompelmi-open-source-secure-file-upload-scanning-node-js/) — Help Net Security (2026-02-02)

package/dist/pompelmi.audit.cjs

@@ -45,7 +45,7 @@ var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
 class AuditTrail {
     constructor(options = {}) {
         this.options = {
-            output: options.output ?? { dest: 'console' },
+            output: options.output ?? { dest: "console" },
             pretty: options.pretty ?? false,
         };
     }
@@ -53,7 +53,7 @@ class AuditTrail {
     logScanComplete(report, extra) {
         const record = {
             timestamp: new Date().toISOString(),
-            event: report.verdict !== 'clean' ? 'threat.detected' : 'scan.complete',
+            event: report.verdict !== "clean" ? "threat.detected" : "scan.complete",
             verdict: report.verdict,
             matchCount: report.matches?.length ?? 0,
             durationMs: report.durationMs,
@@ -67,8 +67,8 @@ class AuditTrail {
     logScanError(error, extra) {
         const record = {
             timestamp: new Date().toISOString(),
-            event: 'scan.error',
-            verdict: 'clean', // unknown at this point
+            event: "scan.error",
+            verdict: "clean", // unknown at this point
             matchCount: 0,
             error: error instanceof Error ? error.message : String(error),
             ...extra,
@@ -79,7 +79,7 @@ class AuditTrail {
     logQuarantine(entry, correlationId) {
         const record = {
             timestamp: new Date().toISOString(),
-            event: 'quarantine.created',
+            event: "quarantine.created",
             quarantineId: entry.id,
             filename: entry.file.originalName,
             sha256: entry.file.sha256,
@@ -92,11 +92,11 @@ class AuditTrail {
     logQuarantineResolved(entry, correlationId) {
         const record = {
             timestamp: new Date().toISOString(),
-            event: entry.status === 'deleted' ? 'quarantine.deleted' : 'quarantine.resolved',
+            event: entry.status === "deleted" ? "quarantine.deleted" : "quarantine.resolved",
             quarantineId: entry.id,
             filename: entry.file.originalName,
             sha256: entry.file.sha256,
-            decision: entry.status === 'promoted' ? 'promote' : 'delete',
+            decision: entry.status === "promoted" ? "promote" : "delete",
             reviewedBy: entry.reviewedBy,
             reviewNote: entry.reviewNote,
             correlationId,
@@ -104,19 +104,17 @@ class AuditTrail {
         void this.write(record);
     }
     async write(record) {
-        const line = this.options.pretty
-            ? JSON.stringify(record, null, 2)
-            : JSON.stringify(record);
+        const line = this.options.pretty ? JSON.stringify(record, null, 2) : JSON.stringify(record);
         const { output } = this.options;
         try {
-            if (output.dest === 'console') {
-                process.stdout.write(line + '\n');
+            if (output.dest === "console") {
+                process.stdout.write(line + "\n");
             }
-            else if (output.dest === 'file') {
+            else if (output.dest === "file") {
                 // Append a newline-delimited JSON (NDJSON) record.
-                await fs__namespace.promises.appendFile(output.path, line + '\n', 'utf8');
+                await fs__namespace.promises.appendFile(output.path, line + "\n", "utf8");
             }
-            else if (output.dest === 'custom') {
+            else if (output.dest === "custom") {
                 await output.write(record);
             }
         }

package/dist/pompelmi.audit.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"pompelmi.audit.cjs","sources":["../src/audit.ts"],"sourcesContent":["/**\n * Audit trail for Pompelmi scan and quarantine events.\n *\n * Produces structured, append-only audit records suitable for:\n *   - compliance logging (HIPAA, SOC 2, ISO 27001)\n *   - SIEM ingestion\n *   - operational dashboards\n *   - incident response\n *\n * Usage:\n * ```ts\n * import { AuditTrail } from 'pompelmi/audit';\n *\n * const audit = new AuditTrail({ dest: 'file', path: './audit.jsonl' });\n * audit.logScanComplete({ filename: 'upload.zip', verdict: 'suspicious', ... });\n * audit.logQuarantine({ entryId: '...', sha256: '...', ... });\n * ```\n *\n * @module audit\n */\n\nimport * as fs from 'fs';\nimport type { ScanReport } from './types';\nimport type { QuarantineEntry } from './quarantine/types';\n\n// ── Record types ──────────────────────────────────────────────────────────────\n\nexport type AuditEventType =\n  | 'scan.complete'\n  | 'scan.error'\n  | 'threat.detected'\n  | 'quarantine.created'\n  | 'quarantine.resolved'\n  | 'quarantine.deleted';\n\ninterface BaseAuditRecord {\n  /** ISO-8601 timestamp. */\n  timestamp: string;\n  /** Event type for structured log routing. */\n  event: AuditEventType;\n  /** Application-assigned session or request id for correlation. */\n  correlationId?: string;\n  /** Uploader identity. */\n  uploadedBy?: string;\n}\n\nexport interface ScanAuditRecord extends BaseAuditRecord {\n  event: 'scan.complete' | 'scan.error' | 'threat.detected';\n  filename?: string;\n  mimeType?: string;\n  sizeBytes?: number;\n  sha256?: string;\n  verdict: ScanReport['verdict'];\n  matchCount: number;\n  durationMs?: number;\n  engine?: string;\n  error?: string;\n}\n\nexport interface QuarantineAuditRecord extends BaseAuditRecord {\n  event: 'quarantine.created' | 'quarantine.resolved' | 'quarantine.deleted';\n  quarantineId: string;\n  filename?: string;\n  sha256: string;\n  decision?: 'promote' | 'delete';\n  reviewedBy?: string;\n  reviewNote?: string;\n}\n\nexport type AuditRecord = ScanAuditRecord | QuarantineAuditRecord;\n\n// ── Destination ───────────────────────────────────────────────────────────────\n\nexport type AuditDest =\n  | { dest: 'console' }\n  | { dest: 'file'; path: string }\n  | { dest: 'custom'; write: (record: AuditRecord) => void | Promise<void> };\n\nexport interface AuditTrailOptions {\n  /** Where to write audit records. Default: 'console'. */\n  output?: AuditDest;\n  /** If true, pretty-print JSON. Useful for debugging. Default: false. */\n  pretty?: boolean;\n}\n\n// ── AuditTrail ────────────────────────────────────────────────────────────────\n\nexport class AuditTrail {\n  private readonly options: Required<AuditTrailOptions>;\n\n  constructor(options: AuditTrailOptions = {}) {\n    this.options = {\n      output: options.output ?? { dest: 'console' },\n      pretty: options.pretty ?? false,\n    };\n  }\n\n  /** Log a completed scan. */\n  logScanComplete(\n    report: ScanReport,\n    extra?: Pick<ScanAuditRecord, 'filename' | 'sizeBytes' | 'sha256' | 'correlationId' | 'uploadedBy'>,\n  ): void {\n    const record: ScanAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: report.verdict !== 'clean' ? 'threat.detected' : 'scan.complete',\n      verdict: report.verdict,\n      matchCount: report.matches?.length ?? 0,\n      durationMs: report.durationMs,\n      engine: report.engine,\n      mimeType: report.file?.mimeType,\n      ...extra,\n    };\n    void this.write(record);\n  }\n\n  /** Log a scan error. */\n  logScanError(\n    error: unknown,\n    extra?: Pick<ScanAuditRecord, 'filename' | 'correlationId' | 'uploadedBy'>,\n  ): void {\n    const record: ScanAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: 'scan.error',\n      verdict: 'clean', // unknown at this point\n      matchCount: 0,\n      error: error instanceof Error ? error.message : String(error),\n      ...extra,\n    };\n    void this.write(record);\n  }\n\n  /** Log a new quarantine entry. */\n  logQuarantine(entry: QuarantineEntry, correlationId?: string): void {\n    const record: QuarantineAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: 'quarantine.created',\n      quarantineId: entry.id,\n      filename: entry.file.originalName,\n      sha256: entry.file.sha256,\n      uploadedBy: entry.file.uploadedBy,\n      correlationId,\n    };\n    void this.write(record);\n  }\n\n  /** Log a quarantine resolution (promote or delete). */\n  logQuarantineResolved(entry: QuarantineEntry, correlationId?: string): void {\n    const record: QuarantineAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: entry.status === 'deleted' ? 'quarantine.deleted' : 'quarantine.resolved',\n      quarantineId: entry.id,\n      filename: entry.file.originalName,\n      sha256: entry.file.sha256,\n      decision: entry.status === 'promoted' ? 'promote' : 'delete',\n      reviewedBy: entry.reviewedBy,\n      reviewNote: entry.reviewNote,\n      correlationId,\n    };\n    void this.write(record);\n  }\n\n  private async write(record: AuditRecord): Promise<void> {\n    const line = this.options.pretty\n      ? JSON.stringify(record, null, 2)\n      : JSON.stringify(record);\n\n    const { output } = this.options;\n\n    try {\n      if (output.dest === 'console') {\n        process.stdout.write(line + '\\n');\n      } else if (output.dest === 'file') {\n        // Append a newline-delimited JSON (NDJSON) record.\n        await fs.promises.appendFile(output.path, line + '\\n', 'utf8');\n      } else if (output.dest === 'custom') {\n        await output.write(record);\n      }\n    } catch {\n      // Audit failures must never interrupt the upload pipeline.\n    }\n  }\n}\n"],"names":["fs"],"mappings":"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"}
+{"version":3,"file":"pompelmi.audit.cjs","sources":["../../src/audit.ts"],"sourcesContent":["/**\n * Audit trail for Pompelmi scan and quarantine events.\n *\n * Produces structured, append-only audit records suitable for:\n *   - compliance logging (HIPAA, SOC 2, ISO 27001)\n *   - SIEM ingestion\n *   - operational dashboards\n *   - incident response\n *\n * Usage:\n * ```ts\n * import { AuditTrail } from 'pompelmi/audit';\n *\n * const audit = new AuditTrail({ dest: 'file', path: './audit.jsonl' });\n * audit.logScanComplete({ filename: 'upload.zip', verdict: 'suspicious', ... });\n * audit.logQuarantine({ entryId: '...', sha256: '...', ... });\n * ```\n *\n * @module audit\n */\n\nimport * as fs from \"fs\";\nimport type { QuarantineEntry } from \"./quarantine/types\";\nimport type { ScanReport } from \"./types\";\n\n// ── Record types ──────────────────────────────────────────────────────────────\n\nexport type AuditEventType =\n  | \"scan.complete\"\n  | \"scan.error\"\n  | \"threat.detected\"\n  | \"quarantine.created\"\n  | \"quarantine.resolved\"\n  | \"quarantine.deleted\";\n\ninterface BaseAuditRecord {\n  /** ISO-8601 timestamp. */\n  timestamp: string;\n  /** Event type for structured log routing. */\n  event: AuditEventType;\n  /** Application-assigned session or request id for correlation. */\n  correlationId?: string;\n  /** Uploader identity. */\n  uploadedBy?: string;\n}\n\nexport interface ScanAuditRecord extends BaseAuditRecord {\n  event: \"scan.complete\" | \"scan.error\" | \"threat.detected\";\n  filename?: string;\n  mimeType?: string;\n  sizeBytes?: number;\n  sha256?: string;\n  verdict: ScanReport[\"verdict\"];\n  matchCount: number;\n  durationMs?: number;\n  engine?: string;\n  error?: string;\n}\n\nexport interface QuarantineAuditRecord extends BaseAuditRecord {\n  event: \"quarantine.created\" | \"quarantine.resolved\" | \"quarantine.deleted\";\n  quarantineId: string;\n  filename?: string;\n  sha256: string;\n  decision?: \"promote\" | \"delete\";\n  reviewedBy?: string;\n  reviewNote?: string;\n}\n\nexport type AuditRecord = ScanAuditRecord | QuarantineAuditRecord;\n\n// ── Destination ───────────────────────────────────────────────────────────────\n\nexport type AuditDest =\n  | { dest: \"console\" }\n  | { dest: \"file\"; path: string }\n  | { dest: \"custom\"; write: (record: AuditRecord) => void | Promise<void> };\n\nexport interface AuditTrailOptions {\n  /** Where to write audit records. Default: 'console'. */\n  output?: AuditDest;\n  /** If true, pretty-print JSON. Useful for debugging. Default: false. */\n  pretty?: boolean;\n}\n\n// ── AuditTrail ────────────────────────────────────────────────────────────────\n\nexport class AuditTrail {\n  private readonly options: Required<AuditTrailOptions>;\n\n  constructor(options: AuditTrailOptions = {}) {\n    this.options = {\n      output: options.output ?? { dest: \"console\" },\n      pretty: options.pretty ?? false,\n    };\n  }\n\n  /** Log a completed scan. */\n  logScanComplete(\n    report: ScanReport,\n    extra?: Pick<\n      ScanAuditRecord,\n      \"filename\" | \"sizeBytes\" | \"sha256\" | \"correlationId\" | \"uploadedBy\"\n    >,\n  ): void {\n    const record: ScanAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: report.verdict !== \"clean\" ? \"threat.detected\" : \"scan.complete\",\n      verdict: report.verdict,\n      matchCount: report.matches?.length ?? 0,\n      durationMs: report.durationMs,\n      engine: report.engine,\n      mimeType: report.file?.mimeType,\n      ...extra,\n    };\n    void this.write(record);\n  }\n\n  /** Log a scan error. */\n  logScanError(\n    error: unknown,\n    extra?: Pick<ScanAuditRecord, \"filename\" | \"correlationId\" | \"uploadedBy\">,\n  ): void {\n    const record: ScanAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: \"scan.error\",\n      verdict: \"clean\", // unknown at this point\n      matchCount: 0,\n      error: error instanceof Error ? error.message : String(error),\n      ...extra,\n    };\n    void this.write(record);\n  }\n\n  /** Log a new quarantine entry. */\n  logQuarantine(entry: QuarantineEntry, correlationId?: string): void {\n    const record: QuarantineAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: \"quarantine.created\",\n      quarantineId: entry.id,\n      filename: entry.file.originalName,\n      sha256: entry.file.sha256,\n      uploadedBy: entry.file.uploadedBy,\n      correlationId,\n    };\n    void this.write(record);\n  }\n\n  /** Log a quarantine resolution (promote or delete). */\n  logQuarantineResolved(entry: QuarantineEntry, correlationId?: string): void {\n    const record: QuarantineAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: entry.status === \"deleted\" ? \"quarantine.deleted\" : \"quarantine.resolved\",\n      quarantineId: entry.id,\n      filename: entry.file.originalName,\n      sha256: entry.file.sha256,\n      decision: entry.status === \"promoted\" ? \"promote\" : \"delete\",\n      reviewedBy: entry.reviewedBy,\n      reviewNote: entry.reviewNote,\n      correlationId,\n    };\n    void this.write(record);\n  }\n\n  private async write(record: AuditRecord): Promise<void> {\n    const line = this.options.pretty ? JSON.stringify(record, null, 2) : JSON.stringify(record);\n\n    const { output } = this.options;\n\n    try {\n      if (output.dest === \"console\") {\n        process.stdout.write(line + \"\\n\");\n      } else if (output.dest === \"file\") {\n        // Append a newline-delimited JSON (NDJSON) record.\n        await fs.promises.appendFile(output.path, line + \"\\n\", \"utf8\");\n      } else if (output.dest === \"custom\") {\n        await output.write(record);\n      }\n    } catch {\n      // Audit failures must never interrupt the upload pipeline.\n    }\n  }\n}\n"],"names":["fs"],"mappings":"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"}

package/dist/pompelmi.audit.esm.js

@@ -24,7 +24,7 @@ import * as fs from 'fs';
 class AuditTrail {
     constructor(options = {}) {
         this.options = {
-            output: options.output ?? { dest: 'console' },
+            output: options.output ?? { dest: "console" },
             pretty: options.pretty ?? false,
         };
     }
@@ -32,7 +32,7 @@ class AuditTrail {
     logScanComplete(report, extra) {
         const record = {
             timestamp: new Date().toISOString(),
-            event: report.verdict !== 'clean' ? 'threat.detected' : 'scan.complete',
+            event: report.verdict !== "clean" ? "threat.detected" : "scan.complete",
             verdict: report.verdict,
             matchCount: report.matches?.length ?? 0,
             durationMs: report.durationMs,
@@ -46,8 +46,8 @@ class AuditTrail {
     logScanError(error, extra) {
         const record = {
             timestamp: new Date().toISOString(),
-            event: 'scan.error',
-            verdict: 'clean', // unknown at this point
+            event: "scan.error",
+            verdict: "clean", // unknown at this point
             matchCount: 0,
             error: error instanceof Error ? error.message : String(error),
             ...extra,
@@ -58,7 +58,7 @@ class AuditTrail {
     logQuarantine(entry, correlationId) {
         const record = {
             timestamp: new Date().toISOString(),
-            event: 'quarantine.created',
+            event: "quarantine.created",
             quarantineId: entry.id,
             filename: entry.file.originalName,
             sha256: entry.file.sha256,
@@ -71,11 +71,11 @@ class AuditTrail {
     logQuarantineResolved(entry, correlationId) {
         const record = {
             timestamp: new Date().toISOString(),
-            event: entry.status === 'deleted' ? 'quarantine.deleted' : 'quarantine.resolved',
+            event: entry.status === "deleted" ? "quarantine.deleted" : "quarantine.resolved",
             quarantineId: entry.id,
             filename: entry.file.originalName,
             sha256: entry.file.sha256,
-            decision: entry.status === 'promoted' ? 'promote' : 'delete',
+            decision: entry.status === "promoted" ? "promote" : "delete",
             reviewedBy: entry.reviewedBy,
             reviewNote: entry.reviewNote,
             correlationId,
@@ -83,19 +83,17 @@ class AuditTrail {
         void this.write(record);
     }
     async write(record) {
-        const line = this.options.pretty
-            ? JSON.stringify(record, null, 2)
-            : JSON.stringify(record);
+        const line = this.options.pretty ? JSON.stringify(record, null, 2) : JSON.stringify(record);
         const { output } = this.options;
         try {
-            if (output.dest === 'console') {
-                process.stdout.write(line + '\n');
+            if (output.dest === "console") {
+                process.stdout.write(line + "\n");
             }
-            else if (output.dest === 'file') {
+            else if (output.dest === "file") {
                 // Append a newline-delimited JSON (NDJSON) record.
-                await fs.promises.appendFile(output.path, line + '\n', 'utf8');
+                await fs.promises.appendFile(output.path, line + "\n", "utf8");
             }
-            else if (output.dest === 'custom') {
+            else if (output.dest === "custom") {
                 await output.write(record);
             }
         }

package/dist/pompelmi.audit.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"pompelmi.audit.esm.js","sources":["../src/audit.ts"],"sourcesContent":["/**\n * Audit trail for Pompelmi scan and quarantine events.\n *\n * Produces structured, append-only audit records suitable for:\n *   - compliance logging (HIPAA, SOC 2, ISO 27001)\n *   - SIEM ingestion\n *   - operational dashboards\n *   - incident response\n *\n * Usage:\n * ```ts\n * import { AuditTrail } from 'pompelmi/audit';\n *\n * const audit = new AuditTrail({ dest: 'file', path: './audit.jsonl' });\n * audit.logScanComplete({ filename: 'upload.zip', verdict: 'suspicious', ... });\n * audit.logQuarantine({ entryId: '...', sha256: '...', ... });\n * ```\n *\n * @module audit\n */\n\nimport * as fs from 'fs';\nimport type { ScanReport } from './types';\nimport type { QuarantineEntry } from './quarantine/types';\n\n// ── Record types ──────────────────────────────────────────────────────────────\n\nexport type AuditEventType =\n  | 'scan.complete'\n  | 'scan.error'\n  | 'threat.detected'\n  | 'quarantine.created'\n  | 'quarantine.resolved'\n  | 'quarantine.deleted';\n\ninterface BaseAuditRecord {\n  /** ISO-8601 timestamp. */\n  timestamp: string;\n  /** Event type for structured log routing. */\n  event: AuditEventType;\n  /** Application-assigned session or request id for correlation. */\n  correlationId?: string;\n  /** Uploader identity. */\n  uploadedBy?: string;\n}\n\nexport interface ScanAuditRecord extends BaseAuditRecord {\n  event: 'scan.complete' | 'scan.error' | 'threat.detected';\n  filename?: string;\n  mimeType?: string;\n  sizeBytes?: number;\n  sha256?: string;\n  verdict: ScanReport['verdict'];\n  matchCount: number;\n  durationMs?: number;\n  engine?: string;\n  error?: string;\n}\n\nexport interface QuarantineAuditRecord extends BaseAuditRecord {\n  event: 'quarantine.created' | 'quarantine.resolved' | 'quarantine.deleted';\n  quarantineId: string;\n  filename?: string;\n  sha256: string;\n  decision?: 'promote' | 'delete';\n  reviewedBy?: string;\n  reviewNote?: string;\n}\n\nexport type AuditRecord = ScanAuditRecord | QuarantineAuditRecord;\n\n// ── Destination ───────────────────────────────────────────────────────────────\n\nexport type AuditDest =\n  | { dest: 'console' }\n  | { dest: 'file'; path: string }\n  | { dest: 'custom'; write: (record: AuditRecord) => void | Promise<void> };\n\nexport interface AuditTrailOptions {\n  /** Where to write audit records. Default: 'console'. */\n  output?: AuditDest;\n  /** If true, pretty-print JSON. Useful for debugging. Default: false. */\n  pretty?: boolean;\n}\n\n// ── AuditTrail ────────────────────────────────────────────────────────────────\n\nexport class AuditTrail {\n  private readonly options: Required<AuditTrailOptions>;\n\n  constructor(options: AuditTrailOptions = {}) {\n    this.options = {\n      output: options.output ?? { dest: 'console' },\n      pretty: options.pretty ?? false,\n    };\n  }\n\n  /** Log a completed scan. */\n  logScanComplete(\n    report: ScanReport,\n    extra?: Pick<ScanAuditRecord, 'filename' | 'sizeBytes' | 'sha256' | 'correlationId' | 'uploadedBy'>,\n  ): void {\n    const record: ScanAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: report.verdict !== 'clean' ? 'threat.detected' : 'scan.complete',\n      verdict: report.verdict,\n      matchCount: report.matches?.length ?? 0,\n      durationMs: report.durationMs,\n      engine: report.engine,\n      mimeType: report.file?.mimeType,\n      ...extra,\n    };\n    void this.write(record);\n  }\n\n  /** Log a scan error. */\n  logScanError(\n    error: unknown,\n    extra?: Pick<ScanAuditRecord, 'filename' | 'correlationId' | 'uploadedBy'>,\n  ): void {\n    const record: ScanAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: 'scan.error',\n      verdict: 'clean', // unknown at this point\n      matchCount: 0,\n      error: error instanceof Error ? error.message : String(error),\n      ...extra,\n    };\n    void this.write(record);\n  }\n\n  /** Log a new quarantine entry. */\n  logQuarantine(entry: QuarantineEntry, correlationId?: string): void {\n    const record: QuarantineAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: 'quarantine.created',\n      quarantineId: entry.id,\n      filename: entry.file.originalName,\n      sha256: entry.file.sha256,\n      uploadedBy: entry.file.uploadedBy,\n      correlationId,\n    };\n    void this.write(record);\n  }\n\n  /** Log a quarantine resolution (promote or delete). */\n  logQuarantineResolved(entry: QuarantineEntry, correlationId?: string): void {\n    const record: QuarantineAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: entry.status === 'deleted' ? 'quarantine.deleted' : 'quarantine.resolved',\n      quarantineId: entry.id,\n      filename: entry.file.originalName,\n      sha256: entry.file.sha256,\n      decision: entry.status === 'promoted' ? 'promote' : 'delete',\n      reviewedBy: entry.reviewedBy,\n      reviewNote: entry.reviewNote,\n      correlationId,\n    };\n    void this.write(record);\n  }\n\n  private async write(record: AuditRecord): Promise<void> {\n    const line = this.options.pretty\n      ? JSON.stringify(record, null, 2)\n      : JSON.stringify(record);\n\n    const { output } = this.options;\n\n    try {\n      if (output.dest === 'console') {\n        process.stdout.write(line + '\\n');\n      } else if (output.dest === 'file') {\n        // Append a newline-delimited JSON (NDJSON) record.\n        await fs.promises.appendFile(output.path, line + '\\n', 'utf8');\n      } else if (output.dest === 'custom') {\n        await output.write(record);\n      }\n    } catch {\n      // Audit failures must never interrupt the upload pipeline.\n    }\n  }\n}\n"],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;;;;;;;AAmBG;AAkEH;MAEa,UAAU,CAAA;AAGrB,IAAA,WAAA,CAAY,UAA6B,EAAE,EAAA;QACzC,IAAI,CAAC,OAAO,GAAG;YACb,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE;AAC7C,YAAA,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK;SAChC;IACH;;IAGA,eAAe,CACb,MAAkB,EAClB,KAAmG,EAAA;AAEnG,QAAA,MAAM,MAAM,GAAoB;AAC9B,YAAA,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;AACnC,YAAA,KAAK,EAAE,MAAM,CAAC,OAAO,KAAK,OAAO,GAAG,iBAAiB,GAAG,eAAe;YACvE,OAAO,EAAE,MAAM,CAAC,OAAO;AACvB,YAAA,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;YACvC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;AACrB,YAAA,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,QAAQ;AAC/B,YAAA,GAAG,KAAK;SACT;AACD,QAAA,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IACzB;;IAGA,YAAY,CACV,KAAc,EACd,KAA0E,EAAA;AAE1E,QAAA,MAAM,MAAM,GAAoB;AAC9B,YAAA,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;AACnC,YAAA,KAAK,EAAE,YAAY;YACnB,OAAO,EAAE,OAAO;AAChB,YAAA,UAAU,EAAE,CAAC;AACb,YAAA,KAAK,EAAE,KAAK,YAAY,KAAK,GAAG,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC;AAC7D,YAAA,GAAG,KAAK;SACT;AACD,QAAA,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IACzB;;IAGA,aAAa,CAAC,KAAsB,EAAE,aAAsB,EAAA;AAC1D,QAAA,MAAM,MAAM,GAA0B;AACpC,YAAA,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;AACnC,YAAA,KAAK,EAAE,oBAAoB;YAC3B,YAAY,EAAE,KAAK,CAAC,EAAE;AACtB,YAAA,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY;AACjC,YAAA,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM;AACzB,YAAA,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU;YACjC,aAAa;SACd;AACD,QAAA,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IACzB;;IAGA,qBAAqB,CAAC,KAAsB,EAAE,aAAsB,EAAA;AAClE,QAAA,MAAM,MAAM,GAA0B;AACpC,YAAA,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;AACnC,YAAA,KAAK,EAAE,KAAK,CAAC,MAAM,KAAK,SAAS,GAAG,oBAAoB,GAAG,qBAAqB;YAChF,YAAY,EAAE,KAAK,CAAC,EAAE;AACtB,YAAA,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY;AACjC,YAAA,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM;AACzB,YAAA,QAAQ,EAAE,KAAK,CAAC,MAAM,KAAK,UAAU,GAAG,SAAS,GAAG,QAAQ;YAC5D,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,aAAa;SACd;AACD,QAAA,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IACzB;IAEQ,MAAM,KAAK,CAAC,MAAmB,EAAA;AACrC,QAAA,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC;cACtB,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;AAChC,cAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;AAE1B,QAAA,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO;AAE/B,QAAA,IAAI;AACF,YAAA,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE;gBAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;YACnC;AAAO,iBAAA,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE;;AAEjC,gBAAA,MAAM,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC;YAChE;AAAO,iBAAA,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE;AACnC,gBAAA,MAAM,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;YAC5B;QACF;AAAE,QAAA,MAAM;;QAER;IACF;AACD;;;;"}
+{"version":3,"file":"pompelmi.audit.esm.js","sources":["../../src/audit.ts"],"sourcesContent":["/**\n * Audit trail for Pompelmi scan and quarantine events.\n *\n * Produces structured, append-only audit records suitable for:\n *   - compliance logging (HIPAA, SOC 2, ISO 27001)\n *   - SIEM ingestion\n *   - operational dashboards\n *   - incident response\n *\n * Usage:\n * ```ts\n * import { AuditTrail } from 'pompelmi/audit';\n *\n * const audit = new AuditTrail({ dest: 'file', path: './audit.jsonl' });\n * audit.logScanComplete({ filename: 'upload.zip', verdict: 'suspicious', ... });\n * audit.logQuarantine({ entryId: '...', sha256: '...', ... });\n * ```\n *\n * @module audit\n */\n\nimport * as fs from \"fs\";\nimport type { QuarantineEntry } from \"./quarantine/types\";\nimport type { ScanReport } from \"./types\";\n\n// ── Record types ──────────────────────────────────────────────────────────────\n\nexport type AuditEventType =\n  | \"scan.complete\"\n  | \"scan.error\"\n  | \"threat.detected\"\n  | \"quarantine.created\"\n  | \"quarantine.resolved\"\n  | \"quarantine.deleted\";\n\ninterface BaseAuditRecord {\n  /** ISO-8601 timestamp. */\n  timestamp: string;\n  /** Event type for structured log routing. */\n  event: AuditEventType;\n  /** Application-assigned session or request id for correlation. */\n  correlationId?: string;\n  /** Uploader identity. */\n  uploadedBy?: string;\n}\n\nexport interface ScanAuditRecord extends BaseAuditRecord {\n  event: \"scan.complete\" | \"scan.error\" | \"threat.detected\";\n  filename?: string;\n  mimeType?: string;\n  sizeBytes?: number;\n  sha256?: string;\n  verdict: ScanReport[\"verdict\"];\n  matchCount: number;\n  durationMs?: number;\n  engine?: string;\n  error?: string;\n}\n\nexport interface QuarantineAuditRecord extends BaseAuditRecord {\n  event: \"quarantine.created\" | \"quarantine.resolved\" | \"quarantine.deleted\";\n  quarantineId: string;\n  filename?: string;\n  sha256: string;\n  decision?: \"promote\" | \"delete\";\n  reviewedBy?: string;\n  reviewNote?: string;\n}\n\nexport type AuditRecord = ScanAuditRecord | QuarantineAuditRecord;\n\n// ── Destination ───────────────────────────────────────────────────────────────\n\nexport type AuditDest =\n  | { dest: \"console\" }\n  | { dest: \"file\"; path: string }\n  | { dest: \"custom\"; write: (record: AuditRecord) => void | Promise<void> };\n\nexport interface AuditTrailOptions {\n  /** Where to write audit records. Default: 'console'. */\n  output?: AuditDest;\n  /** If true, pretty-print JSON. Useful for debugging. Default: false. */\n  pretty?: boolean;\n}\n\n// ── AuditTrail ────────────────────────────────────────────────────────────────\n\nexport class AuditTrail {\n  private readonly options: Required<AuditTrailOptions>;\n\n  constructor(options: AuditTrailOptions = {}) {\n    this.options = {\n      output: options.output ?? { dest: \"console\" },\n      pretty: options.pretty ?? false,\n    };\n  }\n\n  /** Log a completed scan. */\n  logScanComplete(\n    report: ScanReport,\n    extra?: Pick<\n      ScanAuditRecord,\n      \"filename\" | \"sizeBytes\" | \"sha256\" | \"correlationId\" | \"uploadedBy\"\n    >,\n  ): void {\n    const record: ScanAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: report.verdict !== \"clean\" ? \"threat.detected\" : \"scan.complete\",\n      verdict: report.verdict,\n      matchCount: report.matches?.length ?? 0,\n      durationMs: report.durationMs,\n      engine: report.engine,\n      mimeType: report.file?.mimeType,\n      ...extra,\n    };\n    void this.write(record);\n  }\n\n  /** Log a scan error. */\n  logScanError(\n    error: unknown,\n    extra?: Pick<ScanAuditRecord, \"filename\" | \"correlationId\" | \"uploadedBy\">,\n  ): void {\n    const record: ScanAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: \"scan.error\",\n      verdict: \"clean\", // unknown at this point\n      matchCount: 0,\n      error: error instanceof Error ? error.message : String(error),\n      ...extra,\n    };\n    void this.write(record);\n  }\n\n  /** Log a new quarantine entry. */\n  logQuarantine(entry: QuarantineEntry, correlationId?: string): void {\n    const record: QuarantineAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: \"quarantine.created\",\n      quarantineId: entry.id,\n      filename: entry.file.originalName,\n      sha256: entry.file.sha256,\n      uploadedBy: entry.file.uploadedBy,\n      correlationId,\n    };\n    void this.write(record);\n  }\n\n  /** Log a quarantine resolution (promote or delete). */\n  logQuarantineResolved(entry: QuarantineEntry, correlationId?: string): void {\n    const record: QuarantineAuditRecord = {\n      timestamp: new Date().toISOString(),\n      event: entry.status === \"deleted\" ? \"quarantine.deleted\" : \"quarantine.resolved\",\n      quarantineId: entry.id,\n      filename: entry.file.originalName,\n      sha256: entry.file.sha256,\n      decision: entry.status === \"promoted\" ? \"promote\" : \"delete\",\n      reviewedBy: entry.reviewedBy,\n      reviewNote: entry.reviewNote,\n      correlationId,\n    };\n    void this.write(record);\n  }\n\n  private async write(record: AuditRecord): Promise<void> {\n    const line = this.options.pretty ? JSON.stringify(record, null, 2) : JSON.stringify(record);\n\n    const { output } = this.options;\n\n    try {\n      if (output.dest === \"console\") {\n        process.stdout.write(line + \"\\n\");\n      } else if (output.dest === \"file\") {\n        // Append a newline-delimited JSON (NDJSON) record.\n        await fs.promises.appendFile(output.path, line + \"\\n\", \"utf8\");\n      } else if (output.dest === \"custom\") {\n        await output.write(record);\n      }\n    } catch {\n      // Audit failures must never interrupt the upload pipeline.\n    }\n  }\n}\n"],"names":[],"mappings":"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"}