@lincoln504/pi-research 0.1.13 → 1.0.1

package/src/security/github-advisory-types.ts

@@ -0,0 +1,282 @@
+/**
+ * GitHub Advisory API Types
+ */
+
+// ============================================================================
+// Type Definitions for Fetch API
+// ============================================================================
+
+type FetchType = (
+  _input: string | Request,
+  _init?: RequestInit,
+) => Promise<Response>;
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+declare const fetch: FetchType;
+
+interface Headers {
+  append(_name: string, _value: string): void;
+  delete(_name: string): void;
+  get(_name: string): string | null;
+  has(_name: string): boolean;
+  set(_name: string, _value: string): void;
+  forEach(_callback: (_value: string, _name: string) => void): void;
+}
+
+interface Response {
+  readonly headers: Headers;
+  readonly ok: boolean;
+  readonly redirected: boolean;
+  readonly status: number;
+  readonly statusText: string;
+  readonly type: 'basic' | 'cors' | 'default' | 'error' | 'opaque' | 'opaqueredirect';
+  readonly url: string;
+  readonly body: ReadableStream<Uint8Array> | null;
+  readonly bodyUsed: boolean;
+  clone(): Response;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  blob(): Promise<Blob>;
+  formData(): Promise<FormData>;
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+}
+
+// ============================================================================
+// Type Definitions for GitHub API Responses
+// ============================================================================
+
+/**
+ * GitHub Advisory Vulnerability Package
+ */
+export interface GitHubAdvisoryPackage {
+  readonly ecosystem?: string;
+  readonly name?: string;
+}
+
+/**
+ * GitHub Advisory Affected Entry
+ */
+export interface GitHubAdvisoryAffected {
+  readonly package?: GitHubAdvisoryPackage;
+}
+
+/**
+ * GitHub Advisory Vulnerability
+ */
+export interface GitHubAdvisoryVulnerability {
+  readonly package?: GitHubAdvisoryPackage;
+  readonly affected?: readonly GitHubAdvisoryAffected[];
+}
+
+/**
+ * Raw GitHub Advisory from API response
+ */
+export interface GitHubAdvisoryRaw {
+  readonly ghsa_id?: string;
+  readonly id?: string;
+  readonly summary?: string;
+  readonly description?: string;
+  readonly severity?: string;
+  readonly published_at?: string;
+  readonly updated_at?: string;
+  readonly cve_id?: string;
+  readonly html_url?: string;
+  readonly advisory_url?: string;
+  readonly vulnerabilities?: readonly GitHubAdvisoryVulnerability[];
+  readonly affected?: readonly GitHubAdvisoryAffected[];
+}
+
+/**
+ * GitHub API list response wrapper
+ */
+export interface GitHubAdvisoryListResponse {
+  readonly items?: readonly GitHubAdvisoryRaw[];
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export function isGitHubAdvisoryRaw(value: unknown): value is GitHubAdvisoryRaw {
+  return typeof value === 'object' && value !== null;
+}
+
+export function isArray(value: unknown): value is readonly unknown[] {
+  return Array.isArray(value);
+}
+
+export function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+export function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !isArray(value);
+}
+
+export function isGitHubAdvisoryPackage(value: unknown): value is GitHubAdvisoryPackage {
+  if (!isObject(value)) {
+    return false;
+  }
+  return true;
+}
+
+export function isGitHubAdvisoryAffected(value: unknown): value is GitHubAdvisoryAffected {
+  if (!isObject(value)) {
+    return false;
+  }
+  return true;
+}
+
+export function isGitHubAdvisoryVulnerability(value: unknown): value is GitHubAdvisoryVulnerability {
+  if (!isObject(value)) {
+    return false;
+  }
+  return true;
+}
+
+export function isGitHubAdvisoryListResponse(value: unknown): value is GitHubAdvisoryListResponse {
+  if (!isObject(value)) {
+    return false;
+  }
+  return 'items' in value;
+}
+
+export function isGitHubAdvisoryArray(value: unknown): value is GitHubAdvisoryRaw[] {
+  if (!isArray(value)) {
+    return false;
+  }
+  return value.every(isGitHubAdvisoryRaw);
+}
+
+export function isSingleGitHubAdvisory(value: unknown): value is GitHubAdvisoryRaw {
+  if (!isGitHubAdvisoryRaw(value)) {
+    return false;
+  }
+  // Single advisory typically has ghsa_id
+  return 'ghsa_id' in value || 'summary' in value;
+}
+
+import { type Advisory } from './types.ts';
+
+/**
+ * Extract affected packages from an advisory item
+ */
+function extractAffectedPackages(item: GitHubAdvisoryRaw): string[] {
+  const affectedPackages: string[] = [];
+
+  // Check for vulnerabilities array
+  if (item.vulnerabilities !== undefined && isArray(item.vulnerabilities)) {
+    for (const vuln of item.vulnerabilities) {
+      if (!isGitHubAdvisoryVulnerability(vuln)) {
+        continue;
+      }
+
+      // Check for package in various possible locations
+      if (vuln.package !== undefined) {
+        if (isGitHubAdvisoryPackage(vuln.package)) {
+          const ecosystem = vuln.package.ecosystem ?? '';
+          const name = vuln.package.name;
+
+          if (isString(name) && name !== '') {
+            if (ecosystem !== '') {
+              affectedPackages.push(`${ecosystem}/${name}`);
+            } else {
+              affectedPackages.push(name);
+            }
+          }
+        }
+      } else if (vuln.affected !== undefined && isArray(vuln.affected)) {
+        // Alternative structure with 'affected' array
+        for (const aff of vuln.affected) {
+          if (isGitHubAdvisoryAffected(aff) && aff.package !== undefined) {
+            const pkg = aff.package;
+            if (isGitHubAdvisoryPackage(pkg)) {
+              const ecosystem = pkg.ecosystem ?? '';
+              const name = pkg.name;
+
+              if (isString(name) && name !== '') {
+                if (ecosystem !== '') {
+                  affectedPackages.push(`${ecosystem}/${name}`);
+                } else {
+                  affectedPackages.push(name);
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Check for direct 'affected' array at the top level
+  if (affectedPackages.length === 0 && item.affected !== undefined && isArray(item.affected)) {
+    for (const aff of item.affected) {
+      if (isGitHubAdvisoryAffected(aff) && aff.package !== undefined) {
+        const pkg = aff.package;
+        if (isGitHubAdvisoryPackage(pkg)) {
+          const ecosystem = pkg.ecosystem ?? '';
+          const name = pkg.name;
+
+          if (isString(name) && name !== '') {
+            if (ecosystem !== '') {
+              affectedPackages.push(`${ecosystem}/${name}`);
+            } else {
+              affectedPackages.push(name);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return affectedPackages;
+}
+
+/**
+ * Extract references from an advisory item
+ */
+export function extractReferences(item: GitHubAdvisoryRaw): string[] {
+  const references: string[] = [];
+
+  if (item.html_url !== undefined && item.html_url !== '') {
+    references.push(item.html_url);
+  }
+  if (item.advisory_url !== undefined && item.advisory_url !== '') {
+    references.push(item.advisory_url);
+  }
+
+  return references;
+}
+
+/**
+ * Map GitHub advisory to our Advisory interface
+ */
+export function mapGitHubAdvisory(item: GitHubAdvisoryRaw): Advisory {
+  const ghsaId = item.ghsa_id ?? item.id ?? '';
+  const summary = item.summary ?? '';
+  const description = item.description ?? '';
+  // Guard the type: isGitHubAdvisoryRaw validates only that the value is an object, so a
+  // non-string severity (schema drift / numeric code) would throw on .toUpperCase() inside
+  // the unguarded items.map(), failing the whole term in Promise.allSettled and discarding
+  // every advisory for it.
+  const severity = typeof item.severity === 'string' ? item.severity.toUpperCase() : 'UNKNOWN';
+  const published = item.published_at ?? '';
+  const modified = item.updated_at ?? '';
+  const cveId = item.cve_id ?? '';
+
+  const affectedPackages = extractAffectedPackages(item);
+  const references = extractReferences(item);
+
+  return {
+    id: ghsaId,
+    source: 'github',
+    severity,
+    summary,
+    description,
+    published,
+    modified,
+    cveId,
+    references,
+    affectedPackages,
+  };
+}

package/src/security/index.ts

@@ -22,11 +22,12 @@ import type {
   GitHubResult,
   OSVResult,
 } from './types.ts';
-import { REQUEST_DELAY_MS } from '../constants.ts';
-import { searchNVD } from './nvd.ts';
+import { REQUEST_DELAY_MS_NVD, REQUEST_DELAY_MS_OTHER } from '../constants.ts';
+import { searchNVD } from './nvd-client.ts';
 import { searchCisaKev } from './cisa-kev.ts';
 import { searchGitHubAdvisories } from './github-advisories.ts';
-import { searchOSV } from './osv.ts';
+import { searchOSV } from './osv-client.ts';
+import { safeUnref } from '../utils/safe-unref.ts';
 
 // ============================================================================
 // Type Definitions
@@ -50,9 +51,6 @@ interface DatabaseInfoEntry {
 // Helper Functions
 // ============================================================================
 
-/**
- * Type guard to check if a value is a valid Severity
- */
 function isValidSeverity(value: unknown): value is Severity {
   return (
     typeof value === 'string' &&
@@ -60,64 +58,44 @@ function isValidSeverity(value: unknown): value is Severity {
   );
 }
 
-/**
- * Safely extract severity from params, returning undefined if invalid
- */
 function getSeverityParam(params: SecuritySearchParams): Severity | undefined {
-  if (params.severity === undefined) {
-    return undefined;
-  }
+  if (params.severity === undefined) return undefined;
   return isValidSeverity(params.severity) ? params.severity : undefined;
 }
 
-/**
- * Safely extract error message from unknown error
- */
 function getErrorMessage(error: unknown): string {
-  if (error instanceof Error) {
-    return error.message;
-  }
+  if (error instanceof Error) return error.message;
   return String(error);
 }
 
 // ============================================================================
-// Security Searcher Class (with dependency injection)
+// Security Searcher Class
 // ============================================================================
 
-/**
- * Configuration for SecuritySearcher
- */
 export interface SecuritySearcherConfig {
   readonly nvdClient?: INVDClient;
   readonly cisaKevClient?: ICisaKevClient;
   readonly githubAdvisoriesClient?: IGitHubAdvisoriesClient;
   readonly osvClient?: IOSVClient;
-  readonly requestDelay?: number; // milliseconds between requests
+  readonly requestDelay?: number; // Override for testing
 }
 
-const DEFAULT_CONFIG: Required<SecuritySearcherConfig> = {
-  nvdClient: null as unknown as INVDClient,
-  cisaKevClient: null as unknown as ICisaKevClient,
-  githubAdvisoriesClient: null as unknown as IGitHubAdvisoriesClient,
-  osvClient: null as unknown as IOSVClient,
-  requestDelay: REQUEST_DELAY_MS,
+const DEFAULT_CONFIG: SecuritySearcherConfig = {
+  nvdClient: undefined,
+  cisaKevClient: undefined,
+  githubAdvisoriesClient: undefined,
+  osvClient: undefined,
+  requestDelay: -1, // Use database-specific logic by default
 };
 
-/**
- * SecuritySearcher - orchestrates searches across multiple security databases
- * Uses dependency injection for testability
- */
 export class SecuritySearcher {
-  private readonly config: Required<SecuritySearcherConfig>;
+  private readonly config: SecuritySearcherConfig;
 
   constructor(config: Partial<SecuritySearcherConfig> = {}) {
     this.config = { ...DEFAULT_CONFIG, ...config };
   }
 
-  /**
-   * Main search function that queries multiple security databases
-   */
-  async search(params: SecuritySearchParams): Promise<SecuritySearchResult> {
+  async search(params: SecuritySearchParams, signal?: AbortSignal): Promise<SecuritySearchResult> {
     const startTime = Date.now();
     const results: { nvd?: NVDResult; cisa_kev?: CisaKevResult; github?: GitHubResult; osv?: OSVResult } = {};
     const errors: string[] = [];
@@ -125,24 +103,17 @@ export class SecuritySearcher {
 
     const searchPromises: Promise<void>[] = [];
 
-    // Search each requested database in parallel
     if (params.databases.includes('nvd')) {
       searchPromises.push((async () => {
         try {
-          const severity = getSeverityParam(params);
-          const nvdResult = await this.searchNVD(
-            params.terms,
-            {
-              severity: severity,
+          const nvdResult = await this.searchNVD(params.terms, {
+              severity: getSeverityParam(params),
               maxResults: params.maxResults,
               includeExploited: params.includeExploited,
-            },
-          );
+              signal,
+          });
           results.nvd = nvdResult;
           totalVulnerabilities += nvdResult.count;
-          if (nvdResult.error !== undefined) {
-            errors.push(`NVD: ${nvdResult.error}`);
-          }
         } catch (err: unknown) {
           errors.push(`NVD: ${getErrorMessage(err)}`);
         }
@@ -152,14 +123,9 @@ export class SecuritySearcher {
     if (params.databases.includes('cisa_kev')) {
       searchPromises.push((async () => {
         try {
-          const cisaResult = await this.searchCisaKev(params.terms, {
-            maxResults: params.maxResults,
-          });
+          const cisaResult = await this.searchCisaKev(params.terms, { maxResults: params.maxResults, signal });
           results.cisa_kev = cisaResult;
           totalVulnerabilities += cisaResult.count;
-          if (cisaResult.error !== undefined) {
-            errors.push(`CISA KEV: ${cisaResult.error}`);
-          }
         } catch (err: unknown) {
           errors.push(`CISA KEV: ${getErrorMessage(err)}`);
         }
@@ -174,12 +140,10 @@ export class SecuritySearcher {
             severity: params.severity,
             maxResults: params.maxResults,
             repo: params.githubRepo,
+            signal,
           });
           results.github = githubResult;
           totalVulnerabilities += githubResult.count;
-          if (githubResult.error !== undefined) {
-            errors.push(`GitHub: ${githubResult.error}`);
-          }
         } catch (err: unknown) {
           errors.push(`GitHub: ${getErrorMessage(err)}`);
         }
@@ -193,36 +157,45 @@ export class SecuritySearcher {
             ecosystem: params.ecosystem,
             severity: params.severity,
             maxResults: params.maxResults,
+            signal,
           });
           results.osv = osvResult;
           totalVulnerabilities += osvResult.count;
-          if (osvResult.error !== undefined) {
-            errors.push(`OSV: ${osvResult.error}`);
-          }
         } catch (err: unknown) {
           errors.push(`OSV: ${getErrorMessage(err)}`);
         }
       })());
     }
 
-    // Wait for all searches to complete
     await Promise.all(searchPromises);
 
-    // Apply delay to avoid rate limiting for subsequent calls
-    if (this.config.requestDelay > 0) {
+    // Apply delay
+    let delay = this.config.requestDelay ?? -1;
+    if (delay === -1) {
+        delay = params.databases.includes('nvd') ? REQUEST_DELAY_MS_NVD : REQUEST_DELAY_MS_OTHER;
+    }
+
+    if (delay > 0) {
+      // Abortable: a caller cancel must not sit through the post-sweep delay.
       await new Promise<void>((resolve) => {
-        const timeoutId = setTimeout(resolve, this.config.requestDelay);
-        timeoutId.unref();
+        const timeoutId = setTimeout(() => {
+          signal?.removeEventListener('abort', onAbort);
+          resolve();
+        }, delay);
+        safeUnref(timeoutId);
+        const onAbort = () => { clearTimeout(timeoutId); resolve(); };
+        if (signal) signal.addEventListener('abort', onAbort, { once: true });
       });
     }
 
-    const duration = Date.now() - startTime;
-
     return {
       results,
       totalDatabases: Object.keys(results).length,
       totalVulnerabilities,
-      duration,
+      duration: Date.now() - startTime,
+      // Surface databases that threw (vs returned an error field) so a dropped source is visible
+      // rather than silently omitted and mistaken for a clean "no results" from that database.
+      ...(errors.length > 0 ? { errors } : {}),
     };
   }
 
@@ -248,18 +221,13 @@ export class SecuritySearcher {
 }
 
 // ============================================================================
-// Default Client Implementations (wrappers for existing functions)
+// Default Client Implementations
 // ============================================================================
 
 class DefaultNVDClient implements INVDClient {
-  async search(terms: readonly string[], options?: NVDSearchOptions): Promise<import('./types.ts').NVDResult> {
+  async search(terms: readonly string[], options?: NVDSearchOptions): Promise<NVDResult> {
     return searchNVD(terms as string[], options);
   }
-
-  async getById(cveId: string): Promise<import('./types.ts').Vulnerability | null> {
-    const { getCVEById } = await import('./nvd.ts');
-    return getCVEById(cveId);
-  }
 }
 
 class DefaultCisaKevClient implements ICisaKevClient {
@@ -269,138 +237,56 @@ class DefaultCisaKevClient implements ICisaKevClient {
 }
 
 class DefaultGitHubClient implements IGitHubAdvisoriesClient {
-  async search(terms: readonly string[], options?: GitHubSearchOptions): Promise<import('./types.ts').GitHubResult> {
+  async search(terms: readonly string[], options?: GitHubSearchOptions): Promise<GitHubResult> {
     return searchGitHubAdvisories(terms as string[], options);
   }
-
-  async getById(id: string): Promise<import('./types.ts').Advisory | null> {
-    const { getAdvisoryById } = await import('./github-advisories.ts');
-    return getAdvisoryById(id);
-  }
 }
 
 class DefaultOSVClient implements IOSVClient {
-  async search(terms: readonly string[], options?: OSVSearchOptions): Promise<import('./types.ts').OSVResult> {
+  async search(terms: readonly string[], options?: OSVSearchOptions): Promise<OSVResult> {
     return searchOSV(terms as string[], options);
   }
-
-  async getById(osvId: string): Promise<import('./types.ts').Vulnerability | null> {
-    const { getOSVById } = await import('./osv.ts');
-    return getOSVById(osvId);
-  }
-}
-
-// Default client factories
-function createDefaultNVDClient(): INVDClient {
-  return new DefaultNVDClient();
-}
-
-function createDefaultCisaKevClient(): ICisaKevClient {
-  return new DefaultCisaKevClient();
 }
 
-function createDefaultGitHubClient(): IGitHubAdvisoriesClient {
-  return new DefaultGitHubClient();
-}
-
-function createDefaultOSVClient(): IOSVClient {
-  return new DefaultOSVClient();
-}
+function createDefaultNVDClient(): INVDClient { return new DefaultNVDClient(); }
+function createDefaultCisaKevClient(): ICisaKevClient { return new DefaultCisaKevClient(); }
+function createDefaultGitHubClient(): IGitHubAdvisoriesClient { return new DefaultGitHubClient(); }
+function createDefaultOSVClient(): IOSVClient { return new DefaultOSVClient(); }
 
 // ============================================================================
-// Global State for Backward Compatibility
+// Global State
 // ============================================================================
 
 let globalSearcher: SecuritySearcher | null = null;
 
-/**
- * Create a new security searcher instance
- */
-export function createSecuritySearcher(
-  config: Partial<SecuritySearcherConfig> = {}
-): SecuritySearcher {
+export function createSecuritySearcher(config: Partial<SecuritySearcherConfig> = {}): SecuritySearcher {
   return new SecuritySearcher(config);
 }
 
-/**
- * Get the global security searcher instance
- */
 export function getSecuritySearcher(): SecuritySearcher {
-  if (!globalSearcher) {
-    globalSearcher = new SecuritySearcher();
-  }
+  if (!globalSearcher) globalSearcher = new SecuritySearcher();
   return globalSearcher;
 }
 
-/**
- * Set the global security searcher instance (for testing)
- */
-export function setSecuritySearcher(searcher: SecuritySearcher | null): void {
-  globalSearcher = searcher;
-}
-
-/**
- * Reset the global security searcher instance (for testing)
- */
-export function resetSecuritySearcher(): void {
-  globalSearcher = null;
-}
-
-// ============================================================================
-// Backward Compatibility Functions
-// ============================================================================
+export function setSecuritySearcher(searcher: SecuritySearcher | null): void { globalSearcher = searcher; }
+export function resetSecuritySearcher(): void { globalSearcher = null; }
 
-/**
- * Main search function that queries multiple security databases
- * @deprecated Use SecuritySearcher class directly for better testability
- */
-export async function searchSecurityDatabases(
-  params: SecuritySearchParams,
-): Promise<SecuritySearchResult> {
-  const searcher = getSecuritySearcher();
-  return searcher.search(params);
+export async function searchSecurityDatabases(params: SecuritySearchParams, signal?: AbortSignal): Promise<SecuritySearchResult> {
+  return getSecuritySearcher().search(params, signal);
 }
 
-/**
- * Get database info for UI
- */
 export function getDatabaseInfo(): DatabaseInfo {
   return {
     databases: [
-      {
-        id: 'nvd',
-        name: 'NIST NVD',
-        description: 'National Vulnerability Database - 340,000+ CVE records',
-        url: 'https://nvd.nist.gov',
-        free: true,
-      },
-      {
-        id: 'cisa_kev',
-        name: 'CISA KEV Catalog',
-        description: 'Known Exploited Vulnerabilities - actively exploited vulnerabilities',
-        url: 'https://www.cisa.gov/known-exploited-vulnerabilities-catalog',
-        free: true,
-      },
-      {
-        id: 'github',
-        name: 'GitHub Advisory Database',
-        description: 'GitHub Security Advisories - open source security advisories',
-        url: 'https://github.com/advisories',
-        free: true,
-      },
-      {
-        id: 'osv',
-        name: 'Open Source Vulnerabilities',
-        description: 'OSV - open source package vulnerabilities',
-        url: 'https://osv.dev',
-        free: true,
-      },
+      { id: 'nvd', name: 'NIST NVD', description: 'National Vulnerability Database', url: 'https://nvd.nist.gov', free: true },
+      { id: 'cisa_kev', name: 'CISA KEV Catalog', description: 'Known Exploited Vulnerabilities', url: 'https://www.cisa.gov', free: true },
+      { id: 'github', name: 'GitHub Advisory Database', description: 'GitHub Security Advisories', url: 'https://github.com/advisories', free: true },
+      { id: 'osv', name: 'Open Source Vulnerabilities', description: 'OSV - open source package vulnerabilities', url: 'https://osv.dev', free: true },
     ] as const,
   };
 }
 
-// Export individual database search functions for direct use
-export { searchNVD } from './nvd.ts';
+export { searchNVD } from './nvd-client.ts';
 export { searchCisaKev } from './cisa-kev.ts';
 export { searchGitHubAdvisories } from './github-advisories.ts';
-export { searchOSV } from './osv.ts';
+export { searchOSV } from './osv-client.ts';