feat: add npm registry contact extractor (B2/npm)

Signed-off-by: Mouad BANI <mouad-mb@outlook.com>

Author: mbani01

services/apps/packages_worker/src/security-contacts/extractors/registry/index.ts

@@ -0,0 +1,41 @@
+import { Extractor, RawContact, RepoPackage, RepoPolicies } from '../../types'
+
+import { fetchNpm } from './npm'
+import { parsePurl } from './purl'
+
+type EcosystemFetcher = (
+  parsed: ReturnType<typeof parsePurl> & object,
+  pkg: RepoPackage,
+  timeoutMs: number,
+) => Promise<RawContact[]>
+
+// Keyed by the lowercased packages.ecosystem value. go has no manifest contacts.
+const FETCHERS: Record<string, EcosystemFetcher> = {
+  npm: fetchNpm,
+}
+
+export const extractManifest: Extractor = async (target, deps) => {
+  const contacts: RawContact[] = []
+  const policies: Partial<RepoPolicies> = {}
+  const seenPurls = new Set<string>()
+
+  for (const pkg of target.packages) {
+    if (seenPurls.has(pkg.purl)) continue
+    seenPurls.add(pkg.purl)
+
+    const fetcher = FETCHERS[pkg.ecosystem?.toLowerCase()]
+    if (!fetcher) continue
+
+    const parsed = parsePurl(pkg.purl)
+    if (!parsed) continue
+
+    try {
+      contacts.push(...(await fetcher(parsed, pkg, deps.fetchTimeoutMs)))
+    } catch {
+      // one bad package must not sink the rest
+      continue
+    }
+  }
+
+  return { contacts, policies }
+}

services/apps/packages_worker/src/security-contacts/extractors/registry/npm.ts

@@ -0,0 +1,60 @@
+import { ProvenanceEntry, RawContact, RepoPackage } from '../../types'
+import { fetchJson, isEmail } from '../http'
+
+import { ParsedPurl } from './purl'
+
+const SOURCE = 'npm-registry'
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+function npmPackagePath(parsed: ParsedPurl): string {
+  const full = parsed.namespace ? `${parsed.namespace}/${parsed.name}` : parsed.name
+  // Scoped packages must percent-encode the slash for the registry path.
+  return full.startsWith('@') ? full.replace('/', '%2F') : full
+}
+
+export function mapNpm(doc: unknown, sourceUrl: string, fetchedAt: string): RawContact[] {
+  if (!doc || typeof doc !== 'object') return []
+  const d = doc as any
+
+  const declaredAt = typeof d.time?.modified === 'string' ? d.time.modified : undefined
+  const prov = (): ProvenanceEntry[] => [
+    { source: SOURCE, sourceTier: 'B', path: sourceUrl, fetchedAt, declaredAt },
+  ]
+
+  const contacts: RawContact[] = []
+  const seen = new Set<string>()
+  const addEmail = (email: string, name?: string): void => {
+    if (!isEmail(email)) return
+    const key = email.toLowerCase()
+    if (seen.has(key)) return
+    seen.add(key)
+    contacts.push({
+      channel: 'email',
+      value: email,
+      name,
+      role: 'maintainer',
+      tier: 'B',
+      provenance: prov(),
+    })
+  }
+
+  if (typeof d.bugs?.email === 'string') addEmail(d.bugs.email)
+  for (const m of Array.isArray(d.maintainers) ? d.maintainers : []) {
+    if (typeof m?.email === 'string')
+      addEmail(m.email, typeof m.name === 'string' ? m.name : undefined)
+  }
+
+  return contacts
+}
+
+export async function fetchNpm(
+  parsed: ParsedPurl,
+  _pkg: RepoPackage,
+  timeoutMs: number,
+): Promise<RawContact[]> {
+  const url = `https://registry.npmjs.org/${npmPackagePath(parsed)}`
+  const { json } = await fetchJson(url, timeoutMs)
+  if (!json) return []
+  return mapNpm(json, url, new Date().toISOString())
+}

services/apps/packages_worker/src/security-contacts/extractors/registry/purl.ts

@@ -0,0 +1,33 @@
+export interface ParsedPurl {
+  type: string
+  namespace: string | null
+  name: string
+}
+
+/**
+ * Minimal Package URL parser: pkg:TYPE/NAMESPACE/NAME@VERSION?QUALIFIERS#SUBPATH.
+ * Only type/namespace/name are needed to address a registry.
+ */
+export function parsePurl(purl: string): ParsedPurl | null {
+  if (!purl || !purl.startsWith('pkg:')) return null
+
+  let rest = purl.slice('pkg:'.length)
+  rest = rest.split('#')[0].split('?')[0]
+
+  const slash = rest.indexOf('/')
+  if (slash === -1) return null
+
+  const type = rest.slice(0, slash).toLowerCase()
+  let path = rest.slice(slash + 1)
+
+  // Version is the last @ segment (but not a leading @scope on the name).
+  const at = path.lastIndexOf('@')
+  if (at > 0) path = path.slice(0, at)
+
+  const segments = path.split('/').filter(Boolean).map(decodeURIComponent)
+  if (segments.length === 0) return null
+
+  const name = segments[segments.length - 1]
+  const namespace = segments.length > 1 ? segments.slice(0, -1).join('/') : null
+  return { type, namespace, name }
+}