export * from "./pre-upload-types.js"; export { createMagicBytesScanAdapter, type MagicBytesScanAdapterOptions } from "./magic-bytes-adapter.js"; export { DEFAULT_ALLOW_LIST, resolveAllowList } from "./allow-list.js"; export { createClamAVStorageScanner, createClamAVBufferScanner, ClamAVUnreachableError, isClamAVUnreachableError, type ClamAVScannerConfig, type ClamAVBufferScanner, type ClamAVBufferScannerConfig, type ClamScanClient, type ClamScanResult, } from "./clamav-scanner.js"; export { createS3StorageQuarantineAdapter, type S3QuarantineConfig } from "./s3-quarantine.js"; export type ScanVerdict = "clean" | "infected" | "error"; export interface StorageScanTarget { bucket: string; key: string; requestId?: string; metadata?: Record; } export interface StorageScannerInput { bucket: string; key: string; } export type StorageScannerResult = | { verdict: "clean"; engine?: string; } | { verdict: "infected"; signature: string; engine?: string; quarantineKey?: string; }; export interface StorageScanner { scanObject(target: StorageScannerInput): Promise | StorageScannerResult; } export interface StorageQuarantineInput { bucket: string; key: string; quarantineKey?: string; signature: string; } export interface StorageQuarantineResult { bucket?: string; key?: string; quarantineKey?: string; action?: "copied" | "moved" | "tagged" | "skipped"; } export interface StorageQuarantineAdapter { quarantineObject(input: StorageQuarantineInput): Promise | StorageQuarantineResult; } export interface StorageScanDiagnostic { code: StorageScanErrorCode; message: string; upstream?: { name?: string; message?: string; status?: number; requestId?: string; }; } export type StorageScanErrorCode = | "invalid_target" | "scanner_failed" | "quarantine_failed"; export type StorageScanResult = | { verdict: "clean"; bucket: string; key: string; scannedAt: Date; engine?: string; } | { verdict: "infected"; bucket: string; key: string; scannedAt: Date; engine?: string; signature: string; quarantineKey?: string; quarantine?: StorageQuarantineResult; } | { verdict: "error"; bucket?: string; key?: string; scannedAt: Date; error: StorageScanDiagnostic; }; export interface StorageScanService { scanObject(target: StorageScanTarget): Promise; } export interface CreateStorageScanServiceInput { scanner: StorageScanner; quarantine?: StorageQuarantineAdapter; now?: () => Date; } export class StorageScanError extends Error { readonly code: StorageScanErrorCode; readonly details: StorageScanDiagnostic; override readonly cause?: unknown; constructor( code: StorageScanErrorCode, message: string, details: StorageScanDiagnostic, options: { cause?: unknown } = {}, ) { super(message); this.name = "StorageScanError"; this.code = code; this.details = details; this.cause = options.cause; } } export function createStorageScanService({ scanner, quarantine, now = () => new Date(), }: CreateStorageScanServiceInput): StorageScanService { return { async scanObject(target) { const scannedAt = now(); const normalizedTarget = normalizeTarget(target); if (!normalizedTarget) { return { verdict: "error", bucket: isPresent(target.bucket) ? target.bucket : undefined, key: isPresent(target.key) ? target.key : undefined, scannedAt, error: createDiagnostic( "invalid_target", "Storage scan target bucket and key must be non-empty strings.", ), }; } let scanResult: StorageScannerResult; try { scanResult = await scanner.scanObject(normalizedTarget); } catch (cause) { return { verdict: "error", bucket: normalizedTarget.bucket, key: normalizedTarget.key, scannedAt, error: createDiagnostic( "scanner_failed", "Storage scanner failed while scanning object.", cause, ), }; } if (scanResult.verdict === "clean") { return { verdict: "clean", bucket: normalizedTarget.bucket, key: normalizedTarget.key, scannedAt, engine: scanResult.engine, }; } const quarantineKey = scanResult.quarantineKey; let quarantineResult: StorageQuarantineResult | undefined; if (quarantine) { try { quarantineResult = await quarantine.quarantineObject({ bucket: normalizedTarget.bucket, key: normalizedTarget.key, quarantineKey, signature: scanResult.signature, }); } catch (cause) { return { verdict: "error", bucket: normalizedTarget.bucket, key: normalizedTarget.key, scannedAt, error: createDiagnostic( "quarantine_failed", "Storage quarantine failed for infected object.", cause, ), }; } } return { verdict: "infected", bucket: normalizedTarget.bucket, key: normalizedTarget.key, scannedAt, engine: scanResult.engine, signature: scanResult.signature, quarantineKey: quarantineResult?.quarantineKey ?? quarantineKey, quarantine: quarantineResult, }; }, }; } function normalizeTarget(target: StorageScanTarget): StorageScannerInput | null { if (!isPresent(target.bucket) || !isPresent(target.key)) { return null; } return { bucket: target.bucket.trim(), key: target.key.trim(), }; } function createDiagnostic( code: StorageScanErrorCode, message: string, cause?: unknown, ): StorageScanDiagnostic { const upstream = extractRedactedUpstreamDetails(cause); return { code, message, ...(upstream ? { upstream } : {}), }; } function extractRedactedUpstreamDetails( cause: unknown, ): StorageScanDiagnostic["upstream"] { if (!isRecord(cause)) { return undefined; } const metadata = isRecord(cause.$metadata) ? cause.$metadata : undefined; const status = typeof metadata?.httpStatusCode === "number" ? metadata.httpStatusCode : undefined; const requestId = typeof metadata?.requestId === "string" ? metadata.requestId : undefined; const message = typeof cause.message === "string" ? redactSecretLikeText(cause.message) : undefined; return { name: typeof cause.name === "string" ? cause.name : undefined, message, status, requestId, }; } function redactSecretLikeText(message: string): string { return message .replace(/(access[_-]?key(?:id)?|secret[_-]?access[_-]?key|session[_-]?token|credential|authorization|token|password)(\s*[=:]\s*)\S+/gi, "$1$2[redacted]") .replace(/(body)(\s*[=:]\s*)\S+/gi, "$1$2[redacted]"); } function isPresent(value: unknown): value is string { return typeof value === "string" && value.trim().length > 0; } function isRecord(value: unknown): value is Record { return typeof value === "object" && value !== null; }