@uploadista/flow-security-clamscan 0.0.16-beta.1

package/.turbo/turbo-build.log

@@ -0,0 +1,22 @@
+
+
+> @uploadista/flow-security-clamscan@0.0.15 build /Users/denislaboureyras/Documents/uploadista/dev/uploadista-workspace/uploadista-sdk/packages/flow/security/clamscan
+> tsdown
+
+ℹ tsdown v0.16.5 powered by rolldown v1.0.0-beta.50
+ℹ Using tsdown config: /Users/denislaboureyras/Documents/uploadista/dev/uploadista-workspace/uploadista-sdk/packages/flow/security/clamscan/tsdown.config.ts
+ℹ entry: src/index.ts
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ Cleaning 7 files
+ℹ [CJS] dist/index.cjs  2.84 kB │ gzip: 1.17 kB
+ℹ [CJS] 1 files, total: 2.84 kB
+ℹ [ESM] dist/index.mjs        2.25 kB │ gzip: 0.92 kB
+ℹ [ESM] dist/index.mjs.map    9.32 kB │ gzip: 2.88 kB
+ℹ [ESM] dist/index.d.mts.map  0.25 kB │ gzip: 0.17 kB
+ℹ [ESM] dist/index.d.mts      1.65 kB │ gzip: 0.73 kB
+ℹ [ESM] 4 files, total: 13.46 kB
+ℹ [CJS] dist/index.d.cts.map  0.25 kB │ gzip: 0.17 kB
+ℹ [CJS] dist/index.d.cts      1.65 kB │ gzip: 0.73 kB
+ℹ [CJS] 2 files, total: 1.90 kB
+✔ Build complete in 2707ms

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 uploadista
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,256 @@
+# @uploadista/flow-security-clamscan
+
+ClamAV virus scanning plugin for Uploadista Flow. Provides virus and malware detection using the industry-standard ClamAV antivirus engine.
+
+## Installation
+
+```bash
+npm install @uploadista/flow-security-clamscan
+# or
+pnpm add @uploadista/flow-security-clamscan
+# or
+yarn add @uploadista/flow-security-clamscan
+```
+
+## System Requirements
+
+This plugin requires ClamAV to be installed on your system. ClamAV can run in two modes:
+
+1. **clamd daemon** (recommended): Faster, persistent scanning service
+2. **clamscan binary**: Slower but works without daemon
+
+### Installing ClamAV
+
+#### macOS
+
+```bash
+brew install clamav
+# Start the daemon
+brew services start clamav
+```
+
+#### Ubuntu/Debian
+
+```bash
+sudo apt-get update
+sudo apt-get install clamav clamav-daemon
+# Update virus definitions
+sudo freshclam
+# Start daemon
+sudo systemctl start clamav-daemon
+```
+
+#### Fedora/RHEL
+
+```bash
+sudo yum install clamav clamav-update
+sudo freshclam
+sudo systemctl start clamd
+```
+
+#### Docker
+
+Add to your Dockerfile:
+
+```dockerfile
+RUN apt-get update && apt-get install -y clamav clamav-daemon
+RUN freshclam
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { createScanVirusNode } from "@uploadista/flow-security-nodes";
+import { ClamScanPluginLayer } from "@uploadista/flow-security-clamscan";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  // Create virus scan node
+  const scanNode = yield* createScanVirusNode("scan-1", {
+    action: "fail",
+  });
+
+  // Use the node in your flow...
+}).pipe(
+  // Provide ClamAV plugin
+  Effect.provide(ClamScanPluginLayer()),
+);
+```
+
+### Custom Configuration
+
+```typescript
+import { ClamScanPluginLayer } from "@uploadista/flow-security-clamscan";
+
+// Configure ClamAV plugin
+const clamavLayer = ClamScanPluginLayer({
+  preference: "clamdscan", // Use daemon (faster)
+  clamdscan_socket: "/var/run/clamd.scan/clamd.sock", // Custom socket path
+  debug_mode: false,
+});
+
+// Or use TCP connection
+const tcpLayer = ClamScanPluginLayer({
+  preference: "clamdscan",
+  clamdscan_host: "localhost",
+  clamdscan_port: 3310,
+});
+```
+
+### Configuration Options
+
+```typescript
+interface ClamScanConfig {
+  // Scanning method preference
+  preference?: "clamdscan" | "clamscan"; // Default: "clamdscan"
+
+  // Daemon socket path (Unix)
+  clamdscan_socket?: string; // Default: system default
+
+  // TCP connection (alternative to socket)
+  clamdscan_host?: string;
+  clamdscan_port?: number; // Default: 3310
+
+  // Whether to remove infected files (not recommended in flows)
+  remove_infected?: boolean; // Default: false
+
+  // Debug mode
+  debug_mode?: boolean; // Default: false
+}
+```
+
+## How It Works
+
+1. **Initialization**: Plugin initializes ClamAV connection (daemon or binary) on first use
+2. **Temp File**: Input bytes are written to a temporary file
+3. **Scanning**: ClamAV scans the temporary file for viruses
+4. **Cleanup**: Temporary file is deleted after scanning (success or failure)
+5. **Result**: Returns scan results with detected virus names (if any)
+
+### Performance Characteristics
+
+- **Daemon mode (clamdscan)**: ~100-500ms for small files (<1MB)
+- **Binary mode (clamscan)**: ~1-3s per scan (slower, requires process startup)
+- **Large files**: Time increases linearly with file size
+- **Memory**: Efficient stream-based scanning, low memory footprint
+
+## Virus Definitions
+
+ClamAV uses virus definition databases that must be kept up-to-date.
+
+### Update Virus Definitions
+
+```bash
+# Update manually
+sudo freshclam
+
+# Set up automatic updates (cron)
+# Add to crontab:
+0 */6 * * * /usr/bin/freshclam --quiet
+```
+
+### Docker
+
+In your Dockerfile, update definitions at build time:
+
+```dockerfile
+RUN freshclam
+```
+
+For production, set up a cron job or scheduled task to run `freshclam` regularly.
+
+## Testing
+
+You can test virus detection using the EICAR test file - a harmless file that all antivirus software detects as malware:
+
+```typescript
+// EICAR test string (safe, not actual malware)
+const eicarTest = new TextEncoder().encode(
+  'X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*'
+);
+
+const result = yield* virusScanPlugin.scan(eicarTest);
+// result.isClean === false
+// result.detectedViruses === ["Eicar-Test-Signature"]
+```
+
+## Troubleshooting
+
+### "ClamAV is not installed or not available"
+
+- Verify ClamAV is installed: `clamscan --version`
+- Check daemon is running: `systemctl status clamav-daemon` (Linux)
+- Try using binary mode: `preference: "clamscan"`
+
+### "Connection refused" / Daemon not responding
+
+- Ensure daemon is running: `sudo systemctl start clamav-daemon`
+- Check socket path matches your system's configuration
+- Try TCP connection instead of socket
+
+### Scan timeout
+
+- Increase timeout in scan virus node parameters
+- Consider using daemon mode (faster than binary)
+- Check system resources (CPU, memory)
+
+### Outdated virus definitions
+
+```bash
+# Check definitions age
+freshclam --version
+
+# Update definitions
+sudo freshclam
+```
+
+## Examples
+
+### Basic File Scan
+
+```typescript
+import { Effect } from "effect";
+import { ClamScanPluginLayer } from "@uploadista/flow-security-clamscan";
+import { VirusScanPlugin } from "@uploadista/core/flow";
+
+const scanFile = (fileBytes: Uint8Array) =>
+  Effect.gen(function* () {
+    const scanner = yield* VirusScanPlugin;
+
+    const result = yield* scanner.scan(fileBytes);
+
+    if (!result.isClean) {
+      console.log("⚠️  Viruses detected:", result.detectedViruses);
+    } else {
+      console.log("✅ File is clean");
+    }
+
+    return result;
+  }).pipe(Effect.provide(ClamScanPluginLayer()));
+```
+
+### Secure Upload Flow
+
+```typescript
+import { createFlow } from "@uploadista/core/flow";
+import { createScanVirusNode } from "@uploadista/flow-security-nodes";
+import { ClamScanPluginLayer } from "@uploadista/flow-security-clamscan";
+
+const secureFlow = createFlow({
+  nodes: [
+    createInputNode("input"),
+    createScanVirusNode("virus-scan", { action: "fail" }),
+    createStorageNode("storage", { storageId: "uploads" }),
+  ],
+  edges: [
+    { source: "input", target: "virus-scan" },
+    { source: "virus-scan", target: "storage" },
+  ],
+}).pipe(Effect.provide(ClamScanPluginLayer()));
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1 @@
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));let c=require(`node:crypto`),l=require(`node:fs/promises`);l=s(l);let u=require(`node:os`);u=s(u);let d=require(`node:path`);d=s(d);let f=require(`@uploadista/core/errors`),p=require(`@uploadista/core/flow`),m=require(`clamscan`);m=s(m);let h=require(`effect`);var g=class{clamscan=null;constructor(e={}){this.config=e}async initScanner(){if(this.clamscan)return this.clamscan;try{let e=await new m.default().init({preference:this.config.preference??`clamdscan`,remove_infected:this.config.remove_infected??!1,debug_mode:this.config.debug_mode??!1,clamdscan:{socket:this.config.clamdscan_socket,host:this.config.clamdscan_host,port:this.config.clamdscan_port??3310,timeout:6e4,local_fallback:!0},clamscan:{path:`/usr/bin/clamscan`,scan_archives:!0,active:!0}});return this.clamscan=e,e}catch(e){throw Error(`ClamAV initialization failed: ${e instanceof Error?e.message:String(e)}`)}}scan(e){return h.Effect.gen(function*(){let t=yield*h.Effect.tryPromise({try:()=>this.initScanner(),catch:e=>f.UploadistaError.fromCode(`CLAMAV_NOT_INSTALLED`,{body:e instanceof Error?e.message:`ClamAV is not installed or not available`,details:{error:e}})}),n=u.tmpdir(),r=`uploadista-scan-${(0,c.randomUUID)()}`,i=d.join(n,r);return yield*h.Effect.tryPromise({try:()=>l.writeFile(i,e),catch:e=>f.UploadistaError.fromCode(`VIRUS_SCAN_FAILED`,{body:`Failed to create temporary file for scanning`,details:{error:e}})}),yield*h.Effect.tryPromise({try:()=>t.isInfected(i),catch:e=>f.UploadistaError.fromCode(`VIRUS_SCAN_FAILED`,{body:`Virus scan failed: ${e instanceof Error?e.message:String(e)}`,details:{error:e}})}).pipe(h.Effect.map(e=>({isClean:!e.isInfected,detectedViruses:e.viruses||[]})),h.Effect.ensuring(h.Effect.tryPromise({try:()=>l.unlink(i),catch:()=>void 0}).pipe(h.Effect.ignore)))}.bind(this))}getVersion(){return h.Effect.gen(function*(){let e=yield*h.Effect.tryPromise({try:()=>this.initScanner(),catch:e=>f.UploadistaError.fromCode(`CLAMAV_NOT_INSTALLED`,{body:e instanceof Error?e.message:`ClamAV is not installed or not available`,details:{error:e}})});return(yield*h.Effect.tryPromise({try:()=>e.getVersion(),catch:e=>f.UploadistaError.fromCode(`VIRUS_SCAN_FAILED`,{body:`Failed to get ClamAV version`,details:{error:e}})})).version||`Unknown`}.bind(this))}};function _(e={}){return h.Layer.succeed(p.VirusScanPlugin,new g(e))}exports.ClamScanPluginLayer=_;

package/dist/index.d.cts

@@ -0,0 +1,62 @@
+import { ScanMetadata, ScanResult, VirusScanPlugin } from "@uploadista/core/flow";
+import { Layer } from "effect";
+
+//#region src/clamscan-plugin.d.ts
+
+/**
+ * Configuration options for the ClamAV plugin
+ */
+interface ClamScanConfig {
+  /**
+   * Preference for scanning method
+   * - "clamdscan": Use clamd daemon (faster, recommended)
+   * - "clamscan": Use command-line binary
+   */
+  preference?: "clamdscan" | "clamscan";
+  /**
+   * Path to clamd socket (for daemon mode)
+   * Default: /var/run/clamd.scan/clamd.sock
+   */
+  clamdscan_socket?: string;
+  /**
+   * TCP host for clamd (alternative to socket)
+   */
+  clamdscan_host?: string;
+  /**
+   * TCP port for clamd
+   * Default: 3310
+   */
+  clamdscan_port?: number;
+  /**
+   * Whether to remove infected files automatically
+   * Default: false (not recommended in flow context)
+   */
+  remove_infected?: boolean;
+  /**
+   * Debug mode for clamscan library
+   * Default: false
+   */
+  debug_mode?: boolean;
+}
+/**
+ * Creates a VirusScanPlugin layer using ClamAV
+ *
+ * @param config - Optional ClamAV configuration
+ * @returns Layer providing VirusScanPlugin
+ *
+ * @example
+ * ```typescript
+ * // Use with default configuration
+ * const layer = ClamScanPluginLayer();
+ *
+ * // Use with custom configuration
+ * const customLayer = ClamScanPluginLayer({
+ *   preference: "clamdscan",
+ *   clamdscan_socket: "/var/run/clamav/clamd.ctl"
+ * });
+ * ```
+ */
+declare function ClamScanPluginLayer(config?: ClamScanConfig): Layer.Layer<VirusScanPlugin, never, never>;
+//#endregion
+export { type ClamScanConfig, ClamScanPluginLayer, type ScanMetadata, type ScanResult };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/clamscan-plugin.ts"],"sourcesContent":[],"mappings":";;;;;;;AAaA;AA2NgB,UA3NC,cAAA,CA2NkB;EACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBADM,mBAAA,UACN,iBACP,KAAA,CAAM,MAAM"}

package/dist/index.d.mts

@@ -0,0 +1,62 @@
+import { ScanMetadata, ScanResult, VirusScanPlugin } from "@uploadista/core/flow";
+import { Layer } from "effect";
+
+//#region src/clamscan-plugin.d.ts
+
+/**
+ * Configuration options for the ClamAV plugin
+ */
+interface ClamScanConfig {
+  /**
+   * Preference for scanning method
+   * - "clamdscan": Use clamd daemon (faster, recommended)
+   * - "clamscan": Use command-line binary
+   */
+  preference?: "clamdscan" | "clamscan";
+  /**
+   * Path to clamd socket (for daemon mode)
+   * Default: /var/run/clamd.scan/clamd.sock
+   */
+  clamdscan_socket?: string;
+  /**
+   * TCP host for clamd (alternative to socket)
+   */
+  clamdscan_host?: string;
+  /**
+   * TCP port for clamd
+   * Default: 3310
+   */
+  clamdscan_port?: number;
+  /**
+   * Whether to remove infected files automatically
+   * Default: false (not recommended in flow context)
+   */
+  remove_infected?: boolean;
+  /**
+   * Debug mode for clamscan library
+   * Default: false
+   */
+  debug_mode?: boolean;
+}
+/**
+ * Creates a VirusScanPlugin layer using ClamAV
+ *
+ * @param config - Optional ClamAV configuration
+ * @returns Layer providing VirusScanPlugin
+ *
+ * @example
+ * ```typescript
+ * // Use with default configuration
+ * const layer = ClamScanPluginLayer();
+ *
+ * // Use with custom configuration
+ * const customLayer = ClamScanPluginLayer({
+ *   preference: "clamdscan",
+ *   clamdscan_socket: "/var/run/clamav/clamd.ctl"
+ * });
+ * ```
+ */
+declare function ClamScanPluginLayer(config?: ClamScanConfig): Layer.Layer<VirusScanPlugin, never, never>;
+//#endregion
+export { type ClamScanConfig, ClamScanPluginLayer, type ScanMetadata, type ScanResult };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/clamscan-plugin.ts"],"sourcesContent":[],"mappings":";;;;;;;AAaA;AA2NgB,UA3NC,cAAA,CA2NkB;EACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBADM,mBAAA,UACN,iBACP,KAAA,CAAM,MAAM"}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import{randomUUID as e}from"node:crypto";import*as t from"node:fs/promises";import*as n from"node:os";import*as r from"node:path";import{UploadistaError as i}from"@uploadista/core/errors";import{VirusScanPlugin as a}from"@uploadista/core/flow";import o from"clamscan";import{Effect as s,Layer as c}from"effect";var l=class{clamscan=null;constructor(e={}){this.config=e}async initScanner(){if(this.clamscan)return this.clamscan;try{let e=await new o().init({preference:this.config.preference??`clamdscan`,remove_infected:this.config.remove_infected??!1,debug_mode:this.config.debug_mode??!1,clamdscan:{socket:this.config.clamdscan_socket,host:this.config.clamdscan_host,port:this.config.clamdscan_port??3310,timeout:6e4,local_fallback:!0},clamscan:{path:`/usr/bin/clamscan`,scan_archives:!0,active:!0}});return this.clamscan=e,e}catch(e){throw Error(`ClamAV initialization failed: ${e instanceof Error?e.message:String(e)}`)}}scan(a){return s.gen(function*(){let o=yield*s.tryPromise({try:()=>this.initScanner(),catch:e=>i.fromCode(`CLAMAV_NOT_INSTALLED`,{body:e instanceof Error?e.message:`ClamAV is not installed or not available`,details:{error:e}})}),c=n.tmpdir(),l=`uploadista-scan-${e()}`,u=r.join(c,l);return yield*s.tryPromise({try:()=>t.writeFile(u,a),catch:e=>i.fromCode(`VIRUS_SCAN_FAILED`,{body:`Failed to create temporary file for scanning`,details:{error:e}})}),yield*s.tryPromise({try:()=>o.isInfected(u),catch:e=>i.fromCode(`VIRUS_SCAN_FAILED`,{body:`Virus scan failed: ${e instanceof Error?e.message:String(e)}`,details:{error:e}})}).pipe(s.map(e=>({isClean:!e.isInfected,detectedViruses:e.viruses||[]})),s.ensuring(s.tryPromise({try:()=>t.unlink(u),catch:()=>void 0}).pipe(s.ignore)))}.bind(this))}getVersion(){return s.gen(function*(){let e=yield*s.tryPromise({try:()=>this.initScanner(),catch:e=>i.fromCode(`CLAMAV_NOT_INSTALLED`,{body:e instanceof Error?e.message:`ClamAV is not installed or not available`,details:{error:e}})});return(yield*s.tryPromise({try:()=>e.getVersion(),catch:e=>i.fromCode(`VIRUS_SCAN_FAILED`,{body:`Failed to get ClamAV version`,details:{error:e}})})).version||`Unknown`}.bind(this))}};function u(e={}){return c.succeed(a,new l(e))}export{u as ClamScanPluginLayer};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["config: ClamScanConfig"],"sources":["../src/clamscan-plugin.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport * as fs from \"node:fs/promises\";\nimport * as os from \"node:os\";\nimport * as path from \"node:path\";\nimport { UploadistaError } from \"@uploadista/core/errors\";\nimport type { ScanResult, VirusScanPluginShape } from \"@uploadista/core/flow\";\nimport { VirusScanPlugin } from \"@uploadista/core/flow\";\nimport NodeClam from \"clamscan\";\nimport { Effect, Layer } from \"effect\";\n\n/**\n * Configuration options for the ClamAV plugin\n */\nexport interface ClamScanConfig {\n  /**\n   * Preference for scanning method\n   * - \"clamdscan\": Use clamd daemon (faster, recommended)\n   * - \"clamscan\": Use command-line binary\n   */\n  preference?: \"clamdscan\" | \"clamscan\";\n\n  /**\n   * Path to clamd socket (for daemon mode)\n   * Default: /var/run/clamd.scan/clamd.sock\n   */\n  clamdscan_socket?: string;\n\n  /**\n   * TCP host for clamd (alternative to socket)\n   */\n  clamdscan_host?: string;\n\n  /**\n   * TCP port for clamd\n   * Default: 3310\n   */\n  clamdscan_port?: number;\n\n  /**\n   * Whether to remove infected files automatically\n   * Default: false (not recommended in flow context)\n   */\n  remove_infected?: boolean;\n\n  /**\n   * Debug mode for clamscan library\n   * Default: false\n   */\n  debug_mode?: boolean;\n}\n\n/**\n * ClamAV implementation of the VirusScanPlugin\n *\n * This plugin uses the `clamscan` npm package to scan files for viruses\n * using ClamAV antivirus engine. It supports both clamd daemon mode (fast)\n * and binary mode (slower but more portable).\n *\n * @example\n * ```typescript\n * import { ClamScanPluginLayer } from \"@uploadista/flow-security-clamscan\";\n *\n * const program = Effect.gen(function* () {\n *   const virusScan = yield* VirusScanPlugin;\n *   const result = yield* virusScan.scan(fileBytes);\n *   console.log(result.isClean ? \"Clean\" : \"Infected\");\n * }).pipe(Effect.provide(ClamScanPluginLayer));\n * ```\n */\nclass ClamScanPluginImpl implements VirusScanPluginShape {\n  private clamscan: NodeClam | null = null;\n\n  constructor(private config: ClamScanConfig = {}) {}\n\n  /**\n   * Initialize the ClamAV scanner\n   * This is called lazily on first use\n   */\n  private async initScanner(): Promise<NodeClam> {\n    if (this.clamscan) {\n      return this.clamscan;\n    }\n\n    try {\n      // Initialize clamscan with configuration\n      const scanner = await new NodeClam().init({\n        preference: this.config.preference ?? \"clamdscan\",\n        remove_infected: this.config.remove_infected ?? false,\n        debug_mode: this.config.debug_mode ?? false,\n        clamdscan: {\n          socket: this.config.clamdscan_socket,\n          host: this.config.clamdscan_host,\n          port: this.config.clamdscan_port ?? 3310,\n          timeout: 60000,\n          local_fallback: true, // Fall back to binary if daemon unavailable\n        },\n        clamscan: {\n          path: \"/usr/bin/clamscan\", // Standard path\n          scan_archives: true,\n          active: true,\n        },\n      });\n\n      this.clamscan = scanner;\n      return scanner;\n    } catch (error) {\n      // ClamAV not installed or not available\n      throw new Error(\n        `ClamAV initialization failed: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n  }\n\n  /**\n   * Scans a file for viruses using ClamAV\n   *\n   * @param input - File contents as Uint8Array\n   * @returns Effect with scan results\n   */\n  scan(input: Uint8Array): Effect.Effect<ScanResult, UploadistaError> {\n    return Effect.gen(\n      function* (this: ClamScanPluginImpl) {\n        // Initialize scanner (lazy initialization)\n        const scanner = yield* Effect.tryPromise({\n          try: () => this.initScanner(),\n          catch: (error) =>\n            UploadistaError.fromCode(\"CLAMAV_NOT_INSTALLED\", {\n              body:\n                error instanceof Error\n                  ? error.message\n                  : \"ClamAV is not installed or not available\",\n              details: { error },\n            }),\n        });\n\n        // Create temporary file path for scanning\n        const tmpDir = os.tmpdir();\n        const fileName = `uploadista-scan-${randomUUID()}`;\n        const tempFilePath = path.join(tmpDir, fileName);\n\n        // Write file data to temp file\n        yield* Effect.tryPromise({\n          try: () => fs.writeFile(tempFilePath, input),\n          catch: (error) =>\n            UploadistaError.fromCode(\"VIRUS_SCAN_FAILED\", {\n              body: \"Failed to create temporary file for scanning\",\n              details: { error },\n            }),\n        });\n\n        // Scan the file and ensure cleanup\n        const result = yield* Effect.tryPromise({\n          try: () => scanner.isInfected(tempFilePath),\n          catch: (error) =>\n            UploadistaError.fromCode(\"VIRUS_SCAN_FAILED\", {\n              body: `Virus scan failed: ${error instanceof Error ? error.message : String(error)}`,\n              details: { error },\n            }),\n        }).pipe(\n          Effect.map((scanResult) => ({\n            isClean: !scanResult.isInfected,\n            detectedViruses: scanResult.viruses || [],\n          })),\n          Effect.ensuring(\n            // Clean up temporary file (ignore errors)\n            Effect.tryPromise({\n              try: () => fs.unlink(tempFilePath),\n              catch: () => undefined,\n            }).pipe(Effect.ignore),\n          ),\n        );\n\n        return result;\n      }.bind(this),\n    );\n  }\n\n  /**\n   * Gets the ClamAV engine version\n   *\n   * @returns Effect with version string\n   */\n  getVersion(): Effect.Effect<string, UploadistaError> {\n    return Effect.gen(\n      function* (this: ClamScanPluginImpl) {\n        // Initialize scanner (lazy initialization)\n        const scanner = yield* Effect.tryPromise({\n          try: () => this.initScanner(),\n          catch: (error) =>\n            UploadistaError.fromCode(\"CLAMAV_NOT_INSTALLED\", {\n              body:\n                error instanceof Error\n                  ? error.message\n                  : \"ClamAV is not installed or not available\",\n              details: { error },\n            }),\n        });\n\n        // Get version from ClamAV\n        const versionResult = yield* Effect.tryPromise({\n          try: () => scanner.getVersion(),\n          catch: (error) =>\n            UploadistaError.fromCode(\"VIRUS_SCAN_FAILED\", {\n              body: \"Failed to get ClamAV version\",\n              details: { error },\n            }),\n        });\n\n        return versionResult.version || \"Unknown\";\n      }.bind(this),\n    );\n  }\n}\n\n/**\n * Creates a VirusScanPlugin layer using ClamAV\n *\n * @param config - Optional ClamAV configuration\n * @returns Layer providing VirusScanPlugin\n *\n * @example\n * ```typescript\n * // Use with default configuration\n * const layer = ClamScanPluginLayer();\n *\n * // Use with custom configuration\n * const customLayer = ClamScanPluginLayer({\n *   preference: \"clamdscan\",\n *   clamdscan_socket: \"/var/run/clamav/clamd.ctl\"\n * });\n * ```\n */\nexport function ClamScanPluginLayer(\n  config: ClamScanConfig = {},\n): Layer.Layer<VirusScanPlugin, never, never> {\n  return Layer.succeed(VirusScanPlugin, new ClamScanPluginImpl(config));\n}\n"],"mappings":"uTAqEA,IAAM,EAAN,KAAyD,CACvD,SAAoC,KAEpC,YAAY,EAAiC,EAAE,CAAE,CAA7B,KAAA,OAAA,EAMpB,MAAc,aAAiC,CAC7C,GAAI,KAAK,SACP,OAAO,KAAK,SAGd,GAAI,CAEF,IAAM,EAAU,MAAM,IAAI,GAAU,CAAC,KAAK,CACxC,WAAY,KAAK,OAAO,YAAc,YACtC,gBAAiB,KAAK,OAAO,iBAAmB,GAChD,WAAY,KAAK,OAAO,YAAc,GACtC,UAAW,CACT,OAAQ,KAAK,OAAO,iBACpB,KAAM,KAAK,OAAO,eAClB,KAAM,KAAK,OAAO,gBAAkB,KACpC,QAAS,IACT,eAAgB,GACjB,CACD,SAAU,CACR,KAAM,oBACN,cAAe,GACf,OAAQ,GACT,CACF,CAAC,CAGF,MADA,MAAK,SAAW,EACT,QACA,EAAO,CAEd,MAAU,MACR,iCAAiC,aAAiB,MAAQ,EAAM,QAAU,OAAO,EAAM,GACxF,EAUL,KAAK,EAA+D,CAClE,OAAO,EAAO,IACZ,WAAqC,CAEnC,IAAM,EAAU,MAAO,EAAO,WAAW,CACvC,QAAW,KAAK,aAAa,CAC7B,MAAQ,GACN,EAAgB,SAAS,uBAAwB,CAC/C,KACE,aAAiB,MACb,EAAM,QACN,2CACN,QAAS,CAAE,QAAO,CACnB,CAAC,CACL,CAAC,CAGI,EAAS,EAAG,QAAQ,CACpB,EAAW,mBAAmB,GAAY,GAC1C,EAAe,EAAK,KAAK,EAAQ,EAAS,CAkChD,OA/BA,MAAO,EAAO,WAAW,CACvB,QAAW,EAAG,UAAU,EAAc,EAAM,CAC5C,MAAQ,GACN,EAAgB,SAAS,oBAAqB,CAC5C,KAAM,+CACN,QAAS,CAAE,QAAO,CACnB,CAAC,CACL,CAAC,CAGa,MAAO,EAAO,WAAW,CACtC,QAAW,EAAQ,WAAW,EAAa,CAC3C,MAAQ,GACN,EAAgB,SAAS,oBAAqB,CAC5C,KAAM,sBAAsB,aAAiB,MAAQ,EAAM,QAAU,OAAO,EAAM,GAClF,QAAS,CAAE,QAAO,CACnB,CAAC,CACL,CAAC,CAAC,KACD,EAAO,IAAK,IAAgB,CAC1B,QAAS,CAAC,EAAW,WACrB,gBAAiB,EAAW,SAAW,EAAE,CAC1C,EAAE,CACH,EAAO,SAEL,EAAO,WAAW,CAChB,QAAW,EAAG,OAAO,EAAa,CAClC,UAAa,IAAA,GACd,CAAC,CAAC,KAAK,EAAO,OAAO,CACvB,CACF,EAGD,KAAK,KAAK,CACb,CAQH,YAAqD,CACnD,OAAO,EAAO,IACZ,WAAqC,CAEnC,IAAM,EAAU,MAAO,EAAO,WAAW,CACvC,QAAW,KAAK,aAAa,CAC7B,MAAQ,GACN,EAAgB,SAAS,uBAAwB,CAC/C,KACE,aAAiB,MACb,EAAM,QACN,2CACN,QAAS,CAAE,QAAO,CACnB,CAAC,CACL,CAAC,CAYF,OATsB,MAAO,EAAO,WAAW,CAC7C,QAAW,EAAQ,YAAY,CAC/B,MAAQ,GACN,EAAgB,SAAS,oBAAqB,CAC5C,KAAM,+BACN,QAAS,CAAE,QAAO,CACnB,CAAC,CACL,CAAC,EAEmB,SAAW,WAChC,KAAK,KAAK,CACb,GAsBL,SAAgB,EACd,EAAyB,EAAE,CACiB,CAC5C,OAAO,EAAM,QAAQ,EAAiB,IAAI,EAAmB,EAAO,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@uploadista/flow-security-clamscan",
+  "type": "module",
+  "version": "0.0.16-beta.1",
+  "description": "ClamAV virus scanning plugin for Uploadista Flow",
+  "license": "MIT",
+  "author": "Uploadista",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "clamscan": "^2.3.3",
+    "effect": "3.19.4",
+    "zod": "4.1.12",
+    "@uploadista/core": "0.0.16-beta.1"
+  },
+  "devDependencies": {
+    "@effect/vitest": "0.27.0",
+    "@types/node": "24.10.1",
+    "tsdown": "0.16.5",
+    "vitest": "4.0.8",
+    "@uploadista/typescript-config": "0.0.16-beta.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "format": "biome format --write ./src",
+    "lint": "biome lint --write ./src",
+    "check": "biome check --write ./src",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:watch": "vitest watch"
+  }
+}

package/src/clamscan-plugin.ts

@@ -0,0 +1,237 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { UploadistaError } from "@uploadista/core/errors";
+import type { ScanResult, VirusScanPluginShape } from "@uploadista/core/flow";
+import { VirusScanPlugin } from "@uploadista/core/flow";
+import NodeClam from "clamscan";
+import { Effect, Layer } from "effect";
+
+/**
+ * Configuration options for the ClamAV plugin
+ */
+export interface ClamScanConfig {
+  /**
+   * Preference for scanning method
+   * - "clamdscan": Use clamd daemon (faster, recommended)
+   * - "clamscan": Use command-line binary
+   */
+  preference?: "clamdscan" | "clamscan";
+
+  /**
+   * Path to clamd socket (for daemon mode)
+   * Default: /var/run/clamd.scan/clamd.sock
+   */
+  clamdscan_socket?: string;
+
+  /**
+   * TCP host for clamd (alternative to socket)
+   */
+  clamdscan_host?: string;
+
+  /**
+   * TCP port for clamd
+   * Default: 3310
+   */
+  clamdscan_port?: number;
+
+  /**
+   * Whether to remove infected files automatically
+   * Default: false (not recommended in flow context)
+   */
+  remove_infected?: boolean;
+
+  /**
+   * Debug mode for clamscan library
+   * Default: false
+   */
+  debug_mode?: boolean;
+}
+
+/**
+ * ClamAV implementation of the VirusScanPlugin
+ *
+ * This plugin uses the `clamscan` npm package to scan files for viruses
+ * using ClamAV antivirus engine. It supports both clamd daemon mode (fast)
+ * and binary mode (slower but more portable).
+ *
+ * @example
+ * ```typescript
+ * import { ClamScanPluginLayer } from "@uploadista/flow-security-clamscan";
+ *
+ * const program = Effect.gen(function* () {
+ *   const virusScan = yield* VirusScanPlugin;
+ *   const result = yield* virusScan.scan(fileBytes);
+ *   console.log(result.isClean ? "Clean" : "Infected");
+ * }).pipe(Effect.provide(ClamScanPluginLayer));
+ * ```
+ */
+class ClamScanPluginImpl implements VirusScanPluginShape {
+  private clamscan: NodeClam | null = null;
+
+  constructor(private config: ClamScanConfig = {}) {}
+
+  /**
+   * Initialize the ClamAV scanner
+   * This is called lazily on first use
+   */
+  private async initScanner(): Promise<NodeClam> {
+    if (this.clamscan) {
+      return this.clamscan;
+    }
+
+    try {
+      // Initialize clamscan with configuration
+      const scanner = await new NodeClam().init({
+        preference: this.config.preference ?? "clamdscan",
+        remove_infected: this.config.remove_infected ?? false,
+        debug_mode: this.config.debug_mode ?? false,
+        clamdscan: {
+          socket: this.config.clamdscan_socket,
+          host: this.config.clamdscan_host,
+          port: this.config.clamdscan_port ?? 3310,
+          timeout: 60000,
+          local_fallback: true, // Fall back to binary if daemon unavailable
+        },
+        clamscan: {
+          path: "/usr/bin/clamscan", // Standard path
+          scan_archives: true,
+          active: true,
+        },
+      });
+
+      this.clamscan = scanner;
+      return scanner;
+    } catch (error) {
+      // ClamAV not installed or not available
+      throw new Error(
+        `ClamAV initialization failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  /**
+   * Scans a file for viruses using ClamAV
+   *
+   * @param input - File contents as Uint8Array
+   * @returns Effect with scan results
+   */
+  scan(input: Uint8Array): Effect.Effect<ScanResult, UploadistaError> {
+    return Effect.gen(
+      function* (this: ClamScanPluginImpl) {
+        // Initialize scanner (lazy initialization)
+        const scanner = yield* Effect.tryPromise({
+          try: () => this.initScanner(),
+          catch: (error) =>
+            UploadistaError.fromCode("CLAMAV_NOT_INSTALLED", {
+              body:
+                error instanceof Error
+                  ? error.message
+                  : "ClamAV is not installed or not available",
+              details: { error },
+            }),
+        });
+
+        // Create temporary file path for scanning
+        const tmpDir = os.tmpdir();
+        const fileName = `uploadista-scan-${randomUUID()}`;
+        const tempFilePath = path.join(tmpDir, fileName);
+
+        // Write file data to temp file
+        yield* Effect.tryPromise({
+          try: () => fs.writeFile(tempFilePath, input),
+          catch: (error) =>
+            UploadistaError.fromCode("VIRUS_SCAN_FAILED", {
+              body: "Failed to create temporary file for scanning",
+              details: { error },
+            }),
+        });
+
+        // Scan the file and ensure cleanup
+        const result = yield* Effect.tryPromise({
+          try: () => scanner.isInfected(tempFilePath),
+          catch: (error) =>
+            UploadistaError.fromCode("VIRUS_SCAN_FAILED", {
+              body: `Virus scan failed: ${error instanceof Error ? error.message : String(error)}`,
+              details: { error },
+            }),
+        }).pipe(
+          Effect.map((scanResult) => ({
+            isClean: !scanResult.isInfected,
+            detectedViruses: scanResult.viruses || [],
+          })),
+          Effect.ensuring(
+            // Clean up temporary file (ignore errors)
+            Effect.tryPromise({
+              try: () => fs.unlink(tempFilePath),
+              catch: () => undefined,
+            }).pipe(Effect.ignore),
+          ),
+        );
+
+        return result;
+      }.bind(this),
+    );
+  }
+
+  /**
+   * Gets the ClamAV engine version
+   *
+   * @returns Effect with version string
+   */
+  getVersion(): Effect.Effect<string, UploadistaError> {
+    return Effect.gen(
+      function* (this: ClamScanPluginImpl) {
+        // Initialize scanner (lazy initialization)
+        const scanner = yield* Effect.tryPromise({
+          try: () => this.initScanner(),
+          catch: (error) =>
+            UploadistaError.fromCode("CLAMAV_NOT_INSTALLED", {
+              body:
+                error instanceof Error
+                  ? error.message
+                  : "ClamAV is not installed or not available",
+              details: { error },
+            }),
+        });
+
+        // Get version from ClamAV
+        const versionResult = yield* Effect.tryPromise({
+          try: () => scanner.getVersion(),
+          catch: (error) =>
+            UploadistaError.fromCode("VIRUS_SCAN_FAILED", {
+              body: "Failed to get ClamAV version",
+              details: { error },
+            }),
+        });
+
+        return versionResult.version || "Unknown";
+      }.bind(this),
+    );
+  }
+}
+
+/**
+ * Creates a VirusScanPlugin layer using ClamAV
+ *
+ * @param config - Optional ClamAV configuration
+ * @returns Layer providing VirusScanPlugin
+ *
+ * @example
+ * ```typescript
+ * // Use with default configuration
+ * const layer = ClamScanPluginLayer();
+ *
+ * // Use with custom configuration
+ * const customLayer = ClamScanPluginLayer({
+ *   preference: "clamdscan",
+ *   clamdscan_socket: "/var/run/clamav/clamd.ctl"
+ * });
+ * ```
+ */
+export function ClamScanPluginLayer(
+  config: ClamScanConfig = {},
+): Layer.Layer<VirusScanPlugin, never, never> {
+  return Layer.succeed(VirusScanPlugin, new ClamScanPluginImpl(config));
+}

package/src/clamscan.d.ts

@@ -0,0 +1,39 @@
+// Type declarations for clamscan npm package
+declare module "clamscan" {
+  interface ClamScanOptions {
+    preference?: "clamdscan" | "clamscan";
+    remove_infected?: boolean;
+    debug_mode?: boolean;
+    clamdscan?: {
+      socket?: string;
+      host?: string;
+      port?: number;
+      timeout?: number;
+      local_fallback?: boolean;
+    };
+    clamscan?: {
+      path?: string;
+      scan_archives?: boolean;
+      active?: boolean;
+    };
+  }
+
+  interface ScanResult {
+    isInfected: boolean;
+    file: string;
+    viruses: string[];
+  }
+
+  interface VersionResult {
+    version: string;
+  }
+
+  class NodeClam {
+    init(options?: ClamScanOptions): Promise<NodeClam>;
+    isInfected(filePath: string): Promise<ScanResult>;
+    getVersion(): Promise<VersionResult>;
+    scanStream(stream: NodeJS.ReadableStream): Promise<ScanResult>;
+  }
+
+  export = NodeClam;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+// ClamAV virus scanning plugin for Uploadista Flow
+
+// Import from core packages to ensure proper type resolution
+import type {} from "@uploadista/core/types";
+import type {} from "@uploadista/core/upload";
+
+// Re-export types from core for convenience
+export type { ScanMetadata, ScanResult } from "@uploadista/core/flow";
+
+// Export plugin implementation
+export { type ClamScanConfig, ClamScanPluginLayer } from "./clamscan-plugin";

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "@uploadista/typescript-config/server.json",
+  "compilerOptions": {
+    "baseUrl": "./",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

package/tsdown.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: {
+    index: "src/index.ts",
+  },
+  minify: true,
+  format: ["esm", "cjs"],
+  dts: true,
+  outDir: "dist",
+});