davidwindham.com
forked from
npmx.dev/npmx.dev
[READ-ONLY]
a fast, modern browser for the npm registry
1/**
2 * Dependency Analysis Types
3 * Types for vulnerability scanning (via OSV API) and deprecated package detection.
4 *
5 * @see https://google.github.io/osv.dev/api/
6 */
7
8/**
9 * Severity levels in priority order (highest first)
10 */
11export const SEVERITY_LEVELS = ['critical', 'high', 'moderate', 'low'] as const
12
13/**
14 * Severity level derived from CVSS score
15 */
16export type OsvSeverityLevel = (typeof SEVERITY_LEVELS)[number] | 'unknown'
17
18/**
19 * Counts by severity level
20 */
21export type SeverityCounts = Record<(typeof SEVERITY_LEVELS)[number], number>
22
23/**
24 * CVSS severity information from OSV
25 */
26export interface OsvSeverity {
27 type: 'CVSS_V3' | 'CVSS_V4'
28 score: string
29}
30
31/**
32 * Reference link for a vulnerability
33 */
34export interface OsvReference {
35 type: 'ADVISORY' | 'WEB' | 'PACKAGE' | 'REPORT' | 'FIX' | 'ARTICLE' | 'DETECTION' | 'EVIDENCE'
36 url: string
37}
38
39/**
40 * Version range event from OSV affected data
41 * @see https://ossf.github.io/osv-schema/#affectedrangesevents-fields
42 */
43export interface OsvRangeEvent {
44 introduced?: string
45 fixed?: string
46 last_affected?: string
47 limit?: string
48}
49
50/**
51 * Version range from OSV affected data
52 */
53export interface OsvRange {
54 type: 'SEMVER' | 'ECOSYSTEM' | 'GIT'
55 events: OsvRangeEvent[]
56}
57
58/**
59 * Affected package info from OSV
60 */
61export interface OsvAffected {
62 package: {
63 ecosystem: string
64 name: string
65 }
66 ranges?: OsvRange[]
67 versions?: string[]
68}
69
70/**
71 * Individual vulnerability record from OSV
72 */
73export interface OsvVulnerability {
74 id: string
75 summary?: string
76 details?: string
77 aliases?: string[]
78 modified: string
79 published?: string
80 severity?: OsvSeverity[]
81 references?: OsvReference[]
82 affected?: OsvAffected[]
83 database_specific?: {
84 severity?: string
85 cwe_ids?: string[]
86 github_reviewed?: boolean
87 nvd_published_at?: string
88 }
89}
90
91/**
92 * OSV API query response
93 */
94export interface OsvQueryResponse {
95 vulns?: OsvVulnerability[]
96 next_page_token?: string
97}
98
99/**
100 * Single result from OSV batch query (minimal info - just ID and modified)
101 */
102export interface OsvBatchVulnRef {
103 id: string
104 modified: string
105}
106
107/**
108 * Single result in OSV batch response
109 */
110export interface OsvBatchResult {
111 vulns?: OsvBatchVulnRef[]
112 next_page_token?: string
113}
114
115/**
116 * OSV batch query response
117 * @see https://google.github.io/osv.dev/post-v1-querybatch/
118 */
119export interface OsvBatchResponse {
120 results: OsvBatchResult[]
121}
122
123/**
124 * Simplified vulnerability info for display
125 */
126export interface VulnerabilitySummary {
127 id: string
128 summary: string
129 severity: OsvSeverityLevel
130 aliases: string[]
131 url: string
132 /** Version that fixes this vulnerability (if known) */
133 fixedIn?: string
134}
135
136/**
137 * Package vulnerability response returned by our API
138 */
139export interface PackageVulnerabilities {
140 package: string
141 version: string
142 vulnerabilities: VulnerabilitySummary[]
143 counts: SeverityCounts & { total: number }
144}
145
146/** Depth in dependency tree */
147export type DependencyDepth = 'root' | 'direct' | 'transitive'
148
149/**
150 * Vulnerability info for a single package in the tree
151 */
152export interface PackageVulnerabilityInfo {
153 name: string
154 version: string
155 /** Depth in dependency tree: root (0), direct (1), transitive (2+) */
156 depth: DependencyDepth
157 /** Dependency path from root package */
158 path: string[]
159 vulnerabilities: VulnerabilitySummary[]
160 counts: {
161 total: number
162 critical: number
163 high: number
164 moderate: number
165 low: number
166 }
167}
168
169/**
170 * Deprecated package info in the dependency tree
171 */
172export interface DeprecatedPackageInfo {
173 name: string
174 version: string
175 /** Depth in dependency tree: root (0), direct (1), transitive (2+) */
176 depth: DependencyDepth
177 /** Dependency path from root package */
178 path: string[]
179 /** Deprecation message */
180 message: string
181}
182
183/**
184 * Result of dependency tree analysis
185 */
186export interface VulnerabilityTreeResult {
187 /** Root package name */
188 package: string
189 /** Root package version */
190 version: string
191 /** All packages with vulnerabilities in the tree */
192 vulnerablePackages: PackageVulnerabilityInfo[]
193 /** All deprecated packages in the tree */
194 deprecatedPackages: DeprecatedPackageInfo[]
195 /** Total packages analyzed */
196 totalPackages: number
197 /** Number of packages that could not be checked (OSV query failed) */
198 failedQueries: number
199 /** Aggregated counts across all packages */
200 totalCounts: {
201 total: number
202 critical: number
203 high: number
204 moderate: number
205 low: number
206 }
207}