Implement CG-011: VirusTotal HTTP client with caching, quota control, and tests

docs/clawguard-ticket-breakdown.md

@@ -16,7 +16,7 @@ The next unfinished Milestone A tickets now start with:
 
 - `CG-009`: static rule engine and scoring
 - `CG-010`: ClawHub API client
-- `CG-011`: VirusTotal client, caching, and quota control
+- `CG-012`: static report synthesis
 
 ## Epic A: Monorepo Foundation
 
@@ -223,6 +223,7 @@ Acceptance criteria:
 Priority: `P0`
 Milestone: `A`
 Depends on: `CG-002`, `CG-003`
+Status: `Complete`
 
 Scope:
 

packages/integrations/package.json

@@ -14,7 +14,8 @@
   "scripts": {
     "build": "tsc -b",
     "typecheck": "tsc -b --pretty false",
-    "clean": "tsc -b --clean"
+    "clean": "tsc -b --clean",
+    "test": "node --test dist/**/*.test.js"
   },
   "dependencies": {
     "@clawguard/contracts": "workspace:*"

packages/integrations/src/index.ts

@@ -7,3 +7,13 @@ export interface ClawHubClient {
 export interface VirusTotalClient {
   getFileVerdict(contentHash: string): Promise<ThreatIntelVerdict | null>;
 }
+
+export {
+  VirusTotalHttpClient,
+  type VirusTotalAnalysisStatus,
+  type VirusTotalCachePolicy,
+  type VirusTotalClientOptions,
+  type VirusTotalQuotaEvent,
+  type VirusTotalQuotaPolicy,
+  type VirusTotalSearchResult,
+} from "./virustotal-client.js";

packages/integrations/src/virustotal-client.test.ts

@@ -0,0 +1,144 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { VirusTotalHttpClient } from "./virustotal-client.js";
+
+test("getFileVerdict caches successful lookups", async () => {
+  let calls = 0;
+
+  const client = new VirusTotalHttpClient({
+    apiKey: "test-key",
+    fetchImpl: async () => {
+      calls += 1;
+      return new Response(
+        JSON.stringify({
+          data: {
+            attributes: {
+              last_analysis_stats: {
+                malicious: 0,
+                suspicious: 1,
+                harmless: 4,
+                undetected: 10,
+              },
+            },
+          },
+        }),
+        { status: 200 },
+      );
+    },
+  });
+
+  const first = await client.getFileVerdict("abc123");
+  const second = await client.getFileVerdict("abc123");
+
+  assert.equal(calls, 1);
+  assert.equal(first?.verdict, "review");
+  assert.equal(second?.verdict, "review");
+});
+
+test("getFileVerdict deduplicates in-flight requests", async () => {
+  let calls = 0;
+
+  const client = new VirusTotalHttpClient({
+    apiKey: "test-key",
+    fetchImpl: async () => {
+      calls += 1;
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      return new Response(
+        JSON.stringify({
+          data: {
+            attributes: {
+              last_analysis_stats: {
+                malicious: 1,
+                suspicious: 0,
+                harmless: 0,
+                undetected: 0,
+              },
+            },
+          },
+        }),
+        { status: 200 },
+      );
+    },
+  });
+
+  const [a, b] = await Promise.all([
+    client.getFileVerdict("def456"),
+    client.getFileVerdict("def456"),
+  ]);
+
+  assert.equal(calls, 1);
+  assert.equal(a?.verdict, "block");
+  assert.equal(b?.verdict, "block");
+});
+
+test("quota exhaustion degrades cleanly and emits an event", async () => {
+  const events: string[] = [];
+
+  const client = new VirusTotalHttpClient({
+    apiKey: "test-key",
+    quota: { maxRequests: 1, windowMs: 1_000 },
+    onQuotaEvent(event) {
+      events.push(event.reason);
+    },
+    fetchImpl: async () => {
+      return new Response(
+        JSON.stringify({
+          data: {
+            attributes: {
+              last_analysis_stats: {
+                malicious: 0,
+                suspicious: 0,
+                harmless: 1,
+                undetected: 10,
+              },
+            },
+          },
+        }),
+        { status: 200 },
+      );
+    },
+  });
+
+  const first = await client.getDomainVerdict("example.com");
+  const second = await client.getUrlVerdict("https://example.com/path");
+
+  assert.equal(first?.verdict, "allow");
+  assert.equal(second, null);
+  assert.deepEqual(events, ["quota-exhausted"]);
+});
+
+test("submitFileForAnalysis and getAnalysisStatus support async upload flow", async () => {
+  const client = new VirusTotalHttpClient({
+    apiKey: "test-key",
+    fetchImpl: async (url, init) => {
+      if (url.toString().endsWith("/files") && init?.method === "POST") {
+        return new Response(JSON.stringify({ data: { id: "analysis-123" } }), { status: 200 });
+      }
+
+      return new Response(
+        JSON.stringify({
+          data: {
+            attributes: {
+              status: "completed",
+              last_analysis_stats: {
+                malicious: 0,
+                suspicious: 0,
+                harmless: 20,
+                undetected: 5,
+              },
+            },
+          },
+        }),
+        { status: 200 },
+      );
+    },
+  });
+
+  const analysisId = await client.submitFileForAnalysis(new Blob(["sample"]), "sample.bin");
+  const status = await client.getAnalysisStatus("analysis-123");
+
+  assert.equal(analysisId, "analysis-123");
+  assert.equal(status?.status, "completed");
+  assert.equal(status?.verdict?.verdict, "allow");
+});