// ClamAV-backed implementation of the StorageScanner contract from // ./index.ts. Talks to a clamd daemon via the TCP clamscan protocol // (default port 3310). Used by the worker runtime's scan-file job handler. /// import type { StorageScanner, StorageScannerInput, StorageScannerResult } from "./index.js"; export interface ClamAVScannerConfig { host: string; port: number; /** * Connect / scan timeout in ms. clamd can take several seconds on the very * first request after boot while it warms up; 30 s is the operational * default. */ timeoutMs: number; /** * Loader for the upload payload. Returning a Buffer or Readable is fine; * clamscan accepts both via scanStream/scanBuffer. The scanner doesn't read * the object itself so callers (typically the worker job handler) can plug * in any storage backend. */ loadObject: (input: StorageScannerInput) => Promise; /** * Override for the clamscan client constructor. Used by tests; production * leaves it unset so the real npm package is loaded lazily. */ initClient?: (options: { host: string; port: number; timeoutMs: number }) => Promise; /** * Override for the wall clock. Tests inject a stub to make scannedAt * deterministic. */ now?: () => Date; } export interface ClamScanResult { isInfected: boolean | null; viruses?: readonly string[]; } export interface ClamScanClient { /** Returns true when clamd answers a PING within the configured timeout. */ isReachable(): Promise; /** Scan a single in-memory buffer. Throws on transport errors. */ scanBuffer(buffer: Buffer): Promise; /** Scan a stream end-to-end. */ scanStream(stream: NodeJS.ReadableStream): Promise; } const ENGINE = "clamav"; export function createClamAVStorageScanner(config: ClamAVScannerConfig): StorageScanner { const initClient = config.initClient ?? defaultInitClient; let cachedClient: ClamScanClient | undefined; async function getClient(): Promise { if (!cachedClient) { cachedClient = await initClient({ host: config.host, port: config.port, timeoutMs: config.timeoutMs }); } return cachedClient; } return { async scanObject(target: StorageScannerInput): Promise { const client = await getClient(); const reachable = await client.isReachable().catch(() => false); if (!reachable) { throw new ClamAVUnreachableError(`clamd at ${config.host}:${config.port} is unreachable`); } const payload = await config.loadObject(target); const result = await scanWithClient(client, payload); if (result.isInfected) { const signature = result.viruses?.[0] ?? "unknown"; return { verdict: "infected", signature, engine: ENGINE }; } return { verdict: "clean", engine: ENGINE }; }, }; } async function scanWithClient(client: ClamScanClient, payload: Buffer | NodeJS.ReadableStream): Promise { if (Buffer.isBuffer(payload)) { return client.scanBuffer(payload); } return client.scanStream(payload); } async function defaultInitClient({ host, port, timeoutMs }: { host: string; port: number; timeoutMs: number }): Promise { // Lazy import so non-worker bundles (the web app, the API) don't try to // resolve the native clamscan dependency. The clamscan package exports a // factory whose init() returns the client. See clamscan.d.ts in this // directory for the (intentionally narrow) module ambient typing. const mod = await import("clamscan"); const Factory = (mod as { default?: unknown }).default ?? mod; const factory = typeof Factory === "function" ? new (Factory as new () => { init: (opts: unknown) => Promise })() : (Factory as { init: (opts: unknown) => Promise }); const client = (await factory.init({ removeInfected: false, debugMode: false, clamdscan: { host, port, timeout: timeoutMs, localFallback: false, }, preference: "clamdscan", })) as ClamScanLib; return { async isReachable() { const status = await client.ping(); return Boolean(status); }, async scanBuffer(buffer) { const res = await client.scanBuffer(buffer); return { isInfected: res.isInfected, viruses: res.viruses }; }, async scanStream(stream) { const res = await client.scanStream(stream); return { isInfected: res.isInfected, viruses: res.viruses }; }, }; } // Subset of the clamscan npm package surface that we actually use. Avoids a // dependency on @types/clamscan and lets the lazy import stay loose. interface ClamScanLib { ping(): Promise; scanBuffer(buffer: Buffer): Promise<{ isInfected: boolean | null; viruses?: string[] }>; scanStream(stream: NodeJS.ReadableStream): Promise<{ isInfected: boolean | null; viruses?: string[] }>; } export class ClamAVUnreachableError extends Error { constructor(message: string) { super(message); this.name = "ClamAVUnreachableError"; } } export function isClamAVUnreachableError(error: unknown): error is ClamAVUnreachableError { return error instanceof Error && error.name === "ClamAVUnreachableError"; }