feat: add packages api (CM-1334)

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

@@ -0,0 +1,27 @@
+import { Router } from 'express'
+
+import { createRateLimiter } from '@/api/apiRateLimiter'
+import { requireScopes } from '@/api/public/middlewares/requireScopes'
+import { safeWrap } from '@/middlewares/errorMiddleware'
+import { SCOPES } from '@/security/scopes'
+
+import { getAkritesExternalPackageDetail } from '../packages/getAkritesExternalPackageDetail'
+import { getAkritesExternalPackageDetailBatch } from '../packages/getAkritesExternalPackageDetailBatch'
+
+const rateLimiter = createRateLimiter({ max: 60, windowMs: 60 * 1000 })
+
+export function akritesExternalRouter(): Router {
+  const router = Router()
+
+  // TODO: swap for a dedicated cdp:packages:read scope once Akrites gets its own
+  // Auth0 M2M scopes (per the akrites-external draft contract) — reusing the
+  // internal CDP UI scopes for now since that's what's actually issued today.
+  const packagesSubRouter = Router()
+  packagesSubRouter.use(rateLimiter)
+  packagesSubRouter.use(requireScopes([SCOPES.READ_PACKAGES, SCOPES.READ_STEWARDSHIPS], 'all'))
+  packagesSubRouter.get('/detail', safeWrap(getAkritesExternalPackageDetail))
+  packagesSubRouter.post(/^\/detail:batch\/?$/, safeWrap(getAkritesExternalPackageDetailBatch))
+  router.use('/packages', packagesSubRouter)
+
+  return router
+}

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

@@ -0,0 +1,366 @@
+openapi: 3.0.3
+info:
+  title: CDP → Akrites External API
+  version: 0.1.0
+  description: >
+    Read-only external API exposing CDP package security data to the Akrites
+    service. Authenticated via Auth0 M2M client-credentials — CDP only
+    verifies the resulting access token; the assertion exchange happens
+    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.
+
+
+    TODO: scopes below (read:packages, read:stewardships) are the existing
+    internal CDP UI scopes, reused here for now. Swap for a dedicated
+    cdp:packages:read scope once Akrites gets its own Auth0 M2M scopes per
+    the akrites-external draft contract.
+
+servers:
+  - url: https://cm.lfx.dev/api/v1
+    description: Production
+
+security:
+  - M2MBearer:
+      - read:packages
+      - read:stewardships
+
+tags:
+  - name: Packages
+    description: Package detail — requires read:packages and read:stewardships (see TODO above).
+
+components:
+  securitySchemes:
+    M2MBearer:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+  schemas:
+    Error:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: object
+          required: [code, message]
+          properties:
+            code:
+              type: string
+              example: BAD_REQUEST
+            message:
+              type: string
+
+    Ecosystem:
+      type: string
+      example: npm
+
+    HealthBand:
+      type: string
+      enum: [critical, low, medium, high]
+      description: >
+        UNCONFIRMED CROSSWALK — the internal health scale is
+        excellent/healthy/fair/concerning/critical (good→bad); there is no
+        agreed mapping to this critical/low/medium/high scale yet. See
+        HEALTH_BAND_CROSSWALK in akritesExternalPackageDetail.ts. Confirm
+        with Akrites/product before relying on exact band values.
+
+    PackageDetail:
+      type: object
+      required:
+        - purl
+        - name
+        - ecosystem
+        - latestVersion
+        - versionCount
+        - health
+        - impact
+        - riskSignals
+        - security
+        - provenance
+        - supplyChainIntegrity
+      properties:
+        purl:
+          type: string
+        name:
+          type: string
+        ecosystem:
+          $ref: '#/components/schemas/Ecosystem'
+        latestVersion:
+          type: string
+          nullable: true
+        versionCount:
+          type: integer
+          nullable: true
+        health:
+          type: object
+          required: [score, band, subScores, signalCoverageHealth]
+          properties:
+            score:
+              type: integer
+              nullable: true
+              minimum: 0
+              maximum: 100
+            band:
+              $ref: '#/components/schemas/HealthBand'
+            subScores:
+              type: object
+              required: [maintainerHealth, securitySupplyChain, developmentActivity]
+              properties:
+                maintainerHealth:
+                  type: number
+                  nullable: true
+                securitySupplyChain:
+                  type: number
+                  nullable: true
+                developmentActivity:
+                  type: number
+                  nullable: true
+            signalCoverageHealth:
+              type: object
+              nullable: true
+              additionalProperties: true
+        impact:
+          type: object
+          required: [score, downloadsLast30Days, dependentPackagesCount, dependentReposCount, transitiveReach]
+          properties:
+            score:
+              type: integer
+              nullable: true
+              minimum: 0
+              maximum: 100
+            downloadsLast30Days:
+              type: string
+              nullable: true
+              description: Raw registry count string, not normalized.
+            dependentPackagesCount:
+              type: integer
+              nullable: true
+            dependentReposCount:
+              type: integer
+              nullable: true
+            transitiveReach:
+              type: integer
+              nullable: true
+              description: Always null for now — reserved for future computation.
+        riskSignals:
+          type: object
+          required:
+            - lifecycle
+            - maintainerBusFactor
+            - lastReleaseAt
+            - hasSecurityFile
+            - hasSecurityPolicy
+            - branchProtectionEnabled
+            - openssfScorecardScore
+          properties:
+            lifecycle:
+              type: string
+              enum: [active, inactive, deprecated, abandoned, null]
+              nullable: true
+              description: >
+                UNCONFIRMED CROSSWALK from the internal
+                active/stable/declining/abandoned/archived scale — see
+                LIFECYCLE_CROSSWALK in akritesExternalPackageDetail.ts.
+            maintainerBusFactor:
+              type: integer
+              nullable: true
+            lastReleaseAt:
+              type: string
+              format: date-time
+              nullable: true
+            hasSecurityFile:
+              type: boolean
+              nullable: true
+            hasSecurityPolicy:
+              type: boolean
+              nullable: true
+            branchProtectionEnabled:
+              type: boolean
+              nullable: true
+            openssfScorecardScore:
+              type: number
+              format: float
+              minimum: 0
+              maximum: 10
+              nullable: true
+        security:
+          type: object
+          required: [securityPolicyUrl, vulnerabilityReportingUrl, bugBountyUrl, pvrEnabled, criticalVulnerabilityFlag]
+          properties:
+            securityPolicyUrl:
+              type: string
+              nullable: true
+            vulnerabilityReportingUrl:
+              type: string
+              nullable: true
+            bugBountyUrl:
+              type: string
+              nullable: true
+            pvrEnabled:
+              type: boolean
+              nullable: true
+            criticalVulnerabilityFlag:
+              type: boolean
+              nullable: true
+        provenance:
+          type: object
+          required: [resolvedRepositoryUrl, declaredRepositoryUrl, mappingConfidenceScore, mappingConfidenceLabel, lastCommitAt]
+          properties:
+            resolvedRepositoryUrl:
+              type: string
+              nullable: true
+              description: >
+                From the confidence-ranked package_repos → repos join — the
+                repo CDP has actually resolved and enriched (scorecard,
+                branch protection, etc.).
+            declaredRepositoryUrl:
+              type: string
+              nullable: true
+              description: Raw repository URL as declared in the package's own metadata.
+            mappingConfidenceScore:
+              type: number
+              format: float
+              minimum: 0
+              maximum: 1
+              nullable: true
+            mappingConfidenceLabel:
+              type: string
+              enum: [High, Medium, Low, null]
+              nullable: true
+            lastCommitAt:
+              type: string
+              format: date-time
+              nullable: true
+        supplyChainIntegrity:
+          type: object
+          required: [buildProvenance, signedReleases]
+          properties:
+            buildProvenance:
+              type: string
+              nullable: true
+              description: Always null for now — reserved.
+            signedReleases:
+              type: string
+              nullable: true
+              description: Always null for now — reserved.
+
+    PackageDetailBulkEntry:
+      type: object
+      required: [requestedPurl, found, package]
+      properties:
+        requestedPurl:
+          type: string
+        found:
+          type: boolean
+        package:
+          type: object
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/PackageDetail'
+
+paths:
+  /akrites-external/packages/detail:
+    get:
+      operationId: getPackageDetail
+      summary: Get package detail by PURL
+      tags: [Packages]
+      security:
+        - M2MBearer:
+            - read:packages
+            - read:stewardships
+      parameters:
+        - name: purl
+          in: query
+          required: true
+          schema:
+            type: string
+            example: pkg:npm/%40angular/core
+      responses:
+        '200':
+          description: Package detail.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PackageDetail'
+        '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 or read:stewardships scope.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: Package not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /akrites-external/packages/detail:batch:
+    post:
+      operationId: getPackageDetailBatch
+      summary: Bulk package detail lookup
+      tags: [Packages]
+      security:
+        - M2MBearer:
+            - read:packages
+            - read:stewardships
+      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/PackageDetailBulkEntry'
+        '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 or read:stewardships scope.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'