Inbound File Scanning — Implementation Plan

• docs/code-review.html (Aug 28, 2026) — praised the existing upload integrity checks (worker/routes/customer-orders.ts:72, worker/uploads.ts:82) and recommended a scheduled cleanup cron. This plan adds the first real scheduled handler (scan sweep) and reuses the same infrastructure patterns the review endorsed (fail-closed gates, parameterized SQL, shared contracts).
• docs/email-system-explainer.html (planned Aug 29, 2026) — introduces Cloudflare Queues and the email service. This plan rides on the same queue foundation: scan verdicts become order events, and "file quarantined" notifications are a natural consumer of the email system once it lands.

The shop machines download customer artwork (PDF, TIFF, PSD, INDD, DOCX…). Customer uploads come from unauthenticated public endpoints (the code review already flags this), so a crafted file — an EPS/PDF with an embedded exploit, a double-extension executable, or an archive bomb — lands on a shop workstation with zero inspection. The files table (migrations/0000_initial_cloudflare_core.sql:10) tracks only storage_state (pending / available); nothing records whether an object was examined.

Medium Scan asynchronously — never block the customer upload path

worker/routes/customer-orders.ts:22-98

The initiate / upload / complete endpoints stay exactly as they are. Scanning runs out-of-band, so a slow ClamAV engine (250 MB TIFF on a cold container) cannot time out a customer's PUT or the 10-minute presigned TTL (worker/uploads.ts:8). The cost is a window where a file is "available" but not yet scanned — covered by the download gate, which is the only place files leave the system.

Confirmed Scan engine: ClamAV in a Cloudflare Container (decided)

Cloudflare Containers docs, verified Aug 29, 2026

Containers are GA and included with the Workers Paid plan the account already budgets for (docs/CLOUDFLARE_ANNUAL_COST_GUIDE.md:15). A ScanContainer class (@cloudflare/containers) runs the official ClamAV image with clamd + freshclam, and the consumer streams object bytes over the container's fetch using clamd's INSTREAM protocol — no disk writes, works for the full 250 MB max file size (clamd's default MaxScanSize of 100 MB must be raised). No vendor, no per-file cost, customer files never leave Cloudflare. The known trade-off — ClamAV's weaker coverage of targeted/zero-day malware versus commercial engines — is accepted as sufficient for a print shop's inbound artwork.

High Infected files are deleted from R2 immediately (decided)

worker/scanning/scanner.ts (new) · migrations/0000_initial_cloudflare_core.sql:10

When clamd returns a signature match, the consumer deletes the R2 object in the same step that records scan_state = 'infected', so quarantined content does not sit in the bucket awaiting a manual decision. Forensics survive in metadata only: scan_signature (e.g. Win.Test.EICAR_HDB-1) and the file name/size stay in D1, and an internal order event records what was removed. Deletion is irreversible by design — false positives cannot be recovered, so the implementation must:

• delete only after the verdict row is committed (crash between commit and delete is remediated by the cron sweep; the reverse order would leave a clean file gone),
• write the order_events audit row with the signature name before deleting, and
• treat the staff download gate's 'infected' branch as also handling a missing object (409 file_quarantined, never a raw 404 that invites a retry).

Good Trigger with R2 event notifications, back it with a cron sweep

wrangler commands: r2 bucket notification create + queues

An object-create notification rule on the bucket pushes every upload (worker-binding PUT and presigned S3 PUT alike) into file-scan-queue — one mechanism covers both upload modes without touching the upload code. A scheduled handler (the first in this codebase — worker/index.ts:17 currently exports only fetch) sweeps every 5 minutes for files with scan_state = 'pending_scan' older than a threshold, which also covers any notification gap and consumer outages. Deliverability of events from Workers-binding writes should be verified in local dev during step 1; the sweep guarantees correctness either way.

Medium Scan state is a new column, not a new storage_state value

migrations/0000_initial_cloudflare_core.sql:17

storage_state means "does the object exist / is the upload complete" and is written by the upload path. Overloading it with scan verdicts would couple two lifecycles. Migration 0001 adds scan_state, scan_signature, scan_attempts, scan_completed_at to files, defaulting existing rows to 'clean' (pre-scanning era files; the shop can re-scan manually if ever needed — see Open Questions). Purely additive: no drops, renames, or data resets.

States: pending_scan → clean | infected | error, with scan_attempts capping retries at 3 before error is final for that file.

High Enforce at the staff download gate, fail closed

worker/routes/staff-orders.ts:78-100

The download endpoint gains one check before FILES.get: scan_state must be 'clean'. 'pending_scan' returns 409 file_scan_pending ("still being scanned — try again shortly"), 'infected' returns 409 file_quarantined ("removed by virus scanner" — never leaks the signature name to the UI message, and never falls through to a raw 404 even though the object has been deleted), 'error' returns 409 file_scan_unavailable. Same fail-closed style as assertWorkerUploadEnabled (worker/uploads.ts:76). Nothing in the system serves file bytes except this endpoint, so one gate covers everything.

Low Audit trail and staff UX via order events

shared/order-contracts.ts:89-95 · worker/orders/commands.ts:245

Extend OrderEvent["type"] with file_scan_failed and file_quarantined and append rows through the existing appendEvent path. The staff order detail view shows a per-file badge (OrderFile gains scanState): "scanning…", "clean", "quarantined", "scan failed". If the email plan lands first, a quarantined file also emails the shop owner.

Container + consumer protocol

• Image: official ClamAV image, clamd running with freshclam on a loop; clamd.conf raises MaxScanSize/MaxFileSize to 300 MB and StreamMaxLength to 300 MB (files cap at 250 MB per shared/order-contracts.ts:12).
• Instance type: standard-1 (0.5 vCPU / 4 GiB disk 8 GB) minimum — ClamAV's signature DB needs ~2 GiB RAM. sleepAfter ~10 min so idle instances stop billing. Instance types and account limits verified Aug 29, 2026 (image size limit = instance disk size; 50 GB total image storage per account — ClamAV's image is large, keep only current versions pruned).
• Cold start handling: first scan after idle pays container spin-up (~10–30 s); the consumer awaits container.fetch which the @cloudflare/containers client handles transparently. Queue message retention absorbs the delay.
• Message content: the consumer keys off the R2 notification's object.key, looks up the matching files row by object_key, and ignores keys with no row (defensive).
• Idempotency: scans are naturally idempotent; a re-delivered message re-scans and overwrites the same verdict. R2 event notifications dedupe rules apply (one unprefixed rule only — do not add prefix rules).

Verdict handling

• clean → scan_state = 'clean', scan_completed_at set, download unlocked.
• infected → scan_state = 'infected' + scan_signature recorded (internal only), order event appended with the signature name, then the R2 object is deleted (see the deletion decision above). Download permanently blocked.
• error / crash / timeout → scan_attempts + 1; message retried by the queue until max_retries, then cron sweep retries up to 3 total; beyond that scan_state = 'error' + event + alert email. Downloads stay blocked.

• Queue retries → DLQ: consumer throws on transient errors so Queues redelivers; a dead-letter queue catches poison messages; the cron sweep's attempt counter is the final backstop.
• Crash-between-commit-and-delete recovery: the sweep treats any file with scan_state = 'infected' whose object key still exists in R2 as leftover — it deletes the object idempotently. This makes the deletion order (commit first, delete second) safe.
• Container never becomes a dependency: if the container app is down, uploads still succeed end-to-end; files just stay pending_scan and staff downloads gate closed. Staff UI shows "scanning…" so the failure mode is visible, not silent.
• Observability: production already has observability with head sampling (wrangler.production.jsonc:40); scan latency is derivable from scan_completed_at vs object event time in order_events. Add a GET /api/staff/scan/summary (counts by state) as a cheap health check — optional step 7.

• Medium migrations/0001_file_scan_state.sql (new) — additive scan_state, scan_signature, scan_attempts, scan_completed_at; backfill existing rows 'clean'; index on (scan_state, upload/created) for the sweep.
• Good db/schema.ts — mirror the new columns (drizzle npm run db:generate produces 0001).
• Medium shared/order-contracts.ts — FileScanState union, OrderFile.scanState, extend OrderEvent["type"].
• High worker/scanning/container.ts (new) — ScanContainer extends Container (ClamAV, standard-1, sleepAfter).
• High worker/scanning/scanner.ts (new) — queue consumer: resolve file row, stream R2 → clamd INSTREAM, write verdict, append audit event before deleting the object on infection; plus scheduled sweep logic (retries + idempotent infected-object cleanup).
• High worker/routes/staff-orders.ts:82 — extend the gate: stream only when scan_state === 'clean'; distinct error codes per state; 'infected' must short-circuit before FILES.get since the object no longer exists.
• High wrangler.jsonc / wrangler.production.jsonc — containers, Durable Object migration for the container class, queue producer/consumer bindings, triggers.crons (every 5 min).
• Medium scripts/generate-hosted-worker.mjs — carry the container class export, queue consumer, and scheduled handler into the generated production bundle (it already inlines the worker entry; this is the riskiest existing-code touchpoint).
• Low src/app/staff/* — per-file scan badge in order detail; blocked download messaging maps to the new error codes.
• Good tests/ — worker tests: gate refuses pending_scan/infected/error (with the R2 object absent for infected), sweep retries and caps attempts, sweep deletes leftover infected objects, clean unlocks; scanner verdict logic tested with a stub clamd client so CI needs no container. Existing e2e happy path keeps passing (seed files default to 'clean').

• Branch state (Aug 29, 2026): local main is behind origin/main by 1 commit (fast-forwardable). Pull before starting any of this work.
• No destructive changes: one additive migration; no table drops, renames, or resets. The only policy choice with data consequences is the backfill value for pre-existing rows (proposed 'clean' — see Open Questions). Deletion of infected objects is a deliberate, user-confirmed policy: it applies only to files a ClamAV signature flags after this feature ships, never to existing objects.
• This document is private and untracked, like docs/code-review.html and docs/email-system-explainer.html — it must never be committed to git.
• Rollback: revert the worker deploy; the gate disappears but the scan columns and queue infrastructure are inert. No customer-facing path changes.

1. Backfill of existing files: mark pre-scanning rows 'clean' (proposed) or 'pending_scan' so the sweep scans everything historical once (beta volume is small; production has real customer data)? Note: with deletion-on-infection now decided, historical re-scans could remove old files — an argument for simply marking existing rows 'clean'.
2. Production order gating: should an order with unscanned files stay out of the staff "New" queue until all files are 'clean', or is the download gate alone acceptable (proposed)?
3. Consumer placement: queue consumer + container in the main worker (simpler, but the generated production bundle must grow a container class) vs a dedicated scanner worker (isolates the risky generator change, adds a deployable unit)? Proposed: main worker, generator updated carefully.
4. Cost authorization: Containers usage is billed beyond the $5/mo Workers Paid base in docs/CLOUDFLARE_ANNUAL_COST_GUIDE.md; a standard-1 instance idling ~10 min after each upload burst. Acceptable? (Volume here is low — tens of uploads/day.)
5. False-positive recovery path: with deletion irreversible, confirm the shop is comfortable asking the customer to re-send a file in the rare false-positive case (the audit event preserves the file name so the request is specific).