feat: add advisories api (CM-1335) (#4350)

Signed-off-by: Umberto Sgueglia <usgueglia@contractor.linuxfoundation.org>

Author: ulemons

backend/src/api/public/v1/akrites-external/index.ts

@@ -5,6 +5,8 @@ import { requireScopes } from '@/api/public/middlewares/requireScopes'
 import { safeWrap } from '@/middlewares/errorMiddleware'
 import { SCOPES } from '@/security/scopes'
 
+import { getAkritesExternalAdvisoryDetail } from '../packages/getAkritesExternalAdvisoryDetail'
+import { getAkritesExternalAdvisoryDetailBatch } from '../packages/getAkritesExternalAdvisoryDetailBatch'
 import { getAkritesExternalPackageDetail } from '../packages/getAkritesExternalPackageDetail'
 import { getAkritesExternalPackageDetailBatch } from '../packages/getAkritesExternalPackageDetailBatch'
 
@@ -23,5 +25,16 @@ export function akritesExternalRouter(): Router {
   packagesSubRouter.post(/^\/detail:batch\/?$/, safeWrap(getAkritesExternalPackageDetailBatch))
   router.use('/packages', packagesSubRouter)
 
+  // TODO: the contract gates advisories behind a dedicated read:advisories scope
+  // (see the scope-naming note in the akrites-external OpenAPI). That scope isn't
+  // issued by Auth0 yet, so reuse READ_PACKAGES for now — advisories are package
+  // security data and, unlike the packages endpoints above, need no stewardship read.
+  const advisoriesSubRouter = Router()
+  advisoriesSubRouter.use(rateLimiter)
+  advisoriesSubRouter.use(requireScopes([SCOPES.READ_PACKAGES]))
+  advisoriesSubRouter.get('/detail', safeWrap(getAkritesExternalAdvisoryDetail))
+  advisoriesSubRouter.post(/^\/detail:batch\/?$/, safeWrap(getAkritesExternalAdvisoryDetailBatch))
+  router.use('/advisories', advisoriesSubRouter)
+
   return router
 }

backend/src/api/public/v1/akrites-external/openapi.yaml

@@ -9,8 +9,8 @@ info:
     entirely between Akrites and Auth0.
 
 
-    Only the Packages endpoints are implemented so far. Advisories, Blast
-    Radius, and Contacts are specced separately and not yet built.
+    Packages and Advisories endpoints are implemented. Blast Radius and
+    Contacts are specced separately and not yet built.
 
 
     TODO: scopes below (read:packages, read:stewardships) are the existing
@@ -30,6 +30,13 @@ security:
 tags:
   - name: Packages
     description: Package detail — requires read:packages and read:stewardships (see TODO above).
+  - name: Advisories
+    description: >
+      Security advisories for a package, split out of package detail. The draft
+      contract gates these behind a dedicated read:advisories scope; until Auth0
+      issues it, the implementation reuses read:packages (advisories need no
+      stewardship read). Confirm the final scope name (read:advisories vs
+      cdp:advisories:read) with Akrites/product.
 
 components:
   securitySchemes:
@@ -298,6 +305,57 @@ components:
           allOf:
             - $ref: '#/components/schemas/PackageDetail'
 
+    Advisory:
+      type: object
+      required: [osvId, severity, resolution, isCritical]
+      properties:
+        osvId:
+          type: string
+          example: GHSA-xxxx-xxxx-xxxx
+        severity:
+          type: string
+          enum: [critical, high, moderate, low, null]
+          nullable: true
+          description: >
+            Lowercased advisory severity. Any stored value outside this enum is
+            returned as null rather than echoed verbatim.
+        resolution:
+          type: string
+          enum: [open, patched, null]
+          nullable: true
+          description: >
+            Whether the package's latest version is still affected. Null when it
+            can't be determined (no latest version, or no affected ranges recorded).
+        isCritical:
+          type: boolean
+          nullable: true
+          description: cvss >= 7.0. Null when the advisory has no CVSS score.
+
+    AdvisoryDetail:
+      type: object
+      required: [purl, advisories]
+      properties:
+        purl:
+          type: string
+        advisories:
+          type: array
+          items:
+            $ref: '#/components/schemas/Advisory'
+
+    AdvisoryDetailBulkEntry:
+      type: object
+      required: [requestedPurl, found, advisories]
+      properties:
+        requestedPurl:
+          type: string
+        found:
+          type: boolean
+        advisories:
+          type: object
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/AdvisoryDetail'
+
 paths:
   /akrites-external/packages/detail:
     get:
@@ -401,3 +459,104 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+
+  /akrites-external/advisories/detail:
+    get:
+      operationId: getAdvisoryDetail
+      summary: Get advisories for a package by PURL
+      tags: [Advisories]
+      security:
+        - M2MBearer:
+            - read:packages
+      parameters:
+        - name: purl
+          in: query
+          required: true
+          schema:
+            type: string
+            example: pkg:npm/%40angular/core
+      responses:
+        '200':
+          description: Advisories for the package (empty array when the package has none).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdvisoryDetail'
+        '400':
+          description: Malformed purl.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          description: Missing or invalid bearer token.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '403':
+          description: Token missing read:packages scope.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: Package not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /akrites-external/advisories/detail:batch:
+    post:
+      operationId: getAdvisoryDetailBatch
+      summary: Bulk advisory lookup
+      tags: [Advisories]
+      security:
+        - M2MBearer:
+            - read:packages
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [purls]
+              properties:
+                purls:
+                  type: array
+                  minItems: 1
+                  maxItems: 100
+                  items:
+                    type: string
+      responses:
+        '200':
+          description: Results in the same order as the request.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [results]
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/AdvisoryDetailBulkEntry'
+        '400':
+          description: Validation error (empty array, >100 items, malformed purl).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          description: Missing or invalid bearer token.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '403':
+          description: Token missing read:packages scope.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'

backend/src/api/public/v1/packages/akritesExternalAdvisoryDetail.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+
+import type { AkritesExternalAdvisoryRow } from '@crowd/data-access-layer'
+
+import { toAkritesExternalAdvisoryDetail } from './akritesExternalAdvisoryDetail'
+
+const purl = 'pkg:npm/lodash'
+
+function row(overrides: Partial<AkritesExternalAdvisoryRow> = {}): AkritesExternalAdvisoryRow {
+  return {
+    purl,
+    osvId: 'GHSA-1111-1111-1111',
+    severity: 'critical',
+    resolution: 'open',
+    isCritical: true,
+    ...overrides,
+  }
+}
+
+describe('toAkritesExternalAdvisoryDetail', () => {
+  it('maps well-formed advisory rows to the akrites-external shape', () => {
+    const result = toAkritesExternalAdvisoryDetail(purl, [
+      row({ osvId: 'GHSA-aaaa', severity: 'critical', resolution: 'open', isCritical: true }),
+      row({ osvId: 'GHSA-bbbb', severity: 'high', resolution: 'patched', isCritical: false }),
+    ])
+    expect(result.purl).toBe(purl)
+    expect(result.advisories).toEqual([
+      { osvId: 'GHSA-aaaa', severity: 'critical', resolution: 'open', isCritical: true },
+      { osvId: 'GHSA-bbbb', severity: 'high', resolution: 'patched', isCritical: false },
+    ])
+  })
+
+  it('returns an empty advisories array for the found-but-advisory-less sentinel row', () => {
+    // A found package with no advisories comes back as a single null-osvId row.
+    const result = toAkritesExternalAdvisoryDetail(purl, [
+      row({ osvId: null, severity: null, resolution: null, isCritical: null }),
+    ])
+    expect(result.advisories).toEqual([])
+  })
+
+  it('crosswalks the DB medium severity to the contract moderate value', () => {
+    // The DB normalizes the middle band to MEDIUM; the contract calls it moderate.
+    const result = toAkritesExternalAdvisoryDetail(purl, [row({ severity: 'medium' })])
+    expect(result.advisories[0].severity).toBe('moderate')
+  })
+
+  it('coerces a severity outside the known vocabulary to null', () => {
+    const result = toAkritesExternalAdvisoryDetail(purl, [row({ severity: 'info' })])
+    expect(result.advisories[0].severity).toBeNull()
+  })
+
+  it('passes through null severity and null isCritical (unscored advisory)', () => {
+    const result = toAkritesExternalAdvisoryDetail(purl, [
+      row({ osvId: 'GHSA-cccc', severity: null, resolution: 'open', isCritical: null }),
+    ])
+    expect(result.advisories[0]).toEqual({
+      osvId: 'GHSA-cccc',
+      severity: null,
+      resolution: 'open',
+      isCritical: null,
+    })
+  })
+
+  it('keeps the accepted moderate severity value', () => {
+    const result = toAkritesExternalAdvisoryDetail(purl, [row({ severity: 'moderate' })])
+    expect(result.advisories[0].severity).toBe('moderate')
+  })
+})

backend/src/api/public/v1/packages/akritesExternalAdvisoryDetail.ts

@@ -0,0 +1,59 @@
+import type { AkritesExternalAdvisoryRow } from '@crowd/data-access-layer'
+
+export type AkritesExternalAdvisorySeverity = 'critical' | 'high' | 'moderate' | 'low' | null
+export type AkritesExternalAdvisoryResolution = 'open' | 'patched' | null
+
+export interface AkritesExternalAdvisory {
+  osvId: string
+  severity: AkritesExternalAdvisorySeverity
+  resolution: AkritesExternalAdvisoryResolution
+  isCritical: boolean | null
+}
+
+export interface AkritesExternalAdvisoryDetail {
+  purl: string
+  advisories: AkritesExternalAdvisory[]
+}
+
+export interface AdvisoryDetailBulkEntry {
+  requestedPurl: string
+  found: boolean
+  advisories: AkritesExternalAdvisoryDetail | null
+}
+
+// Maps the DB's (lowercased) severity vocabulary to the contract's enum. The DB
+// normalizes the middle band to MEDIUM (initial_schema.sql; osv/extractSeverity.ts),
+// whereas the Akrites contract calls that same level `moderate` — hence the explicit
+// medium → moderate crosswalk. Anything unrecognized (or null) maps to null so the
+// response never violates the published enum.
+const SEVERITY_CROSSWALK: Record<string, AkritesExternalAdvisorySeverity> = {
+  critical: 'critical',
+  high: 'high',
+  medium: 'moderate',
+  moderate: 'moderate',
+  low: 'low',
+}
+
+function toAkritesSeverity(severity: string | null): AkritesExternalAdvisorySeverity {
+  if (severity === null) return null
+  return SEVERITY_CROSSWALK[severity] ?? null
+}
+
+// Builds the AdvisoryDetail for a single purl from its DAL rows. Rows carry a null
+// osvId sentinel for a found-but-advisory-less package (see AkritesExternalAdvisoryRow) —
+// those are dropped here so `advisories` is an empty array, not a list with a null entry.
+export function toAkritesExternalAdvisoryDetail(
+  purl: string,
+  rows: AkritesExternalAdvisoryRow[],
+): AkritesExternalAdvisoryDetail {
+  const advisories: AkritesExternalAdvisory[] = rows
+    .filter((r): r is AkritesExternalAdvisoryRow & { osvId: string } => r.osvId !== null)
+    .map((r) => ({
+      osvId: r.osvId,
+      severity: toAkritesSeverity(r.severity),
+      resolution: r.resolution,
+      isCritical: r.isCritical,
+    }))
+
+  return { purl, advisories }
+}

backend/src/api/public/v1/packages/getAkritesExternalAdvisoryDetail.ts

@@ -0,0 +1,26 @@
+import type { Request, Response } from 'express'
+
+import { NotFoundError } from '@crowd/common'
+import { getAdvisoriesByPurls } from '@crowd/data-access-layer'
+
+import { getPackagesQx } from '@/db/packagesDb'
+import { ok } from '@/utils/api'
+import { validateOrThrow } from '@/utils/validation'
+
+import { toAkritesExternalAdvisoryDetail } from './akritesExternalAdvisoryDetail'
+import { purlQuerySchema } from './purl'
+
+export async function getAkritesExternalAdvisoryDetail(req: Request, res: Response): Promise<void> {
+  const { purl } = validateOrThrow(purlQuerySchema, req.query)
+
+  const qx = await getPackagesQx()
+  const rows = await getAdvisoriesByPurls(qx, [purl])
+
+  // No rows at all means the package itself doesn't exist. A package that exists but
+  // has no advisories still yields one (null-osvId) sentinel row, so it 200s with [].
+  if (rows.length === 0) {
+    throw new NotFoundError()
+  }
+
+  ok(res, toAkritesExternalAdvisoryDetail(purl, rows))
+}