feat(dlx): add Socket Firewall API check before package downloads

- Split Arborist reify into buildIdealTree → firewall check → reify
- Check all resolved deps against public firewall-api.socket.dev/purl
- Block on critical/high severity alerts, non-fatal on API errors
- Add npmPurl() for PURL construction (scoped + unscoped packages)
- Add SOCKET_LIB_VERSION/USER_AGENT constants (build-time inlined via INLINED_LIB_VERSION)
- Extend Arborist type definitions for idealTree/inventory access
- Update default User-Agent in httpRequest to use lib identity

Author: jdalton

.config/esbuild.config.mjs

@@ -3,6 +3,7 @@
  * Fast JS compilation with esbuild, declarations with tsgo
  */
 
+import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import process from 'node:process'
@@ -12,6 +13,9 @@ import { envAsBoolean } from '@socketsecurity/lib-stable/env/helpers'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const rootPath = path.join(__dirname, '..')
+const rootPkgJson = JSON.parse(
+  fs.readFileSync(path.join(rootPath, 'package.json'), 'utf8'),
+)
 const srcPath = path.join(rootPath, 'src')
 const distPath = path.join(rootPath, 'dist')
 
@@ -275,6 +279,8 @@ export const buildConfig = {
     'process.env.NODE_ENV': JSON.stringify(
       process.env.NODE_ENV || 'production',
     ),
+    'process.env.INLINED_LIB_VERSION': JSON.stringify(rootPkgJson.version),
+    'process.env["INLINED_LIB_VERSION"]': JSON.stringify(rootPkgJson.version),
   },
 
   // Banner for generated code

.config/vitest.config.mts

@@ -2,13 +2,17 @@
  * @fileoverview Vitest configuration for socket-lib
  */
 
+import { readFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import process from 'node:process'
 import { defineConfig } from 'vitest/config'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const projectRoot = path.resolve(__dirname, '..')
+const rootPkgJson = JSON.parse(
+  readFileSync(path.join(projectRoot, 'package.json'), 'utf8'),
+)
 
 // Normalize paths for cross-platform glob patterns (forward slashes on Windows)
 const toGlobPath = (pathLike: string): string => pathLike.replaceAll('\\', '/')
@@ -38,6 +42,9 @@ const vitestConfig = defineConfig({
     },
   },
   test: {
+    env: {
+      INLINED_LIB_VERSION: rootPkgJson.version,
+    },
     globalSetup: [path.resolve(__dirname, 'vitest-global-setup.mts')],
     globals: false,
     environment: 'node',

src/constants/socket.ts

@@ -39,6 +39,13 @@ export const SOCKET_FIREWALL_APP_NAME = 'sfw'
 export const SOCKET_REGISTRY_APP_NAME = 'registry'
 export const SOCKET_APP_PREFIX = '_'
 
+// Socket.dev lib.
+export const SOCKET_LIB_NAME = '@socketsecurity/lib'
+export const SOCKET_LIB_VERSION: string =
+  process.env['INLINED_LIB_VERSION'] ?? '0.0.0'
+export const SOCKET_LIB_URL = 'https://github.com/SocketDev/socket-lib'
+export const SOCKET_LIB_USER_AGENT = `socketsecurity-lib/${SOCKET_LIB_VERSION} (${SOCKET_LIB_URL})`
+
 // Socket.dev IPC.
 export const SOCKET_IPC_HANDSHAKE = 'SOCKET_IPC_HANDSHAKE'
 

src/dlx/package.ts

@@ -31,11 +31,13 @@
  */
 
 import { WIN32 } from '../constants/platform'
+import { SOCKET_LIB_USER_AGENT } from '../constants/socket'
 import { generateCacheKey } from './cache'
 import Arborist from '../external/@npmcli/arborist'
 import libnpmexec from '../external/libnpmexec'
 import npmPackageArg from '../external/npm-package-arg'
 import { readJsonSync, safeMkdir } from '../fs'
+import { httpJson } from '../http-request'
 import { normalizePath } from '../paths/normalize'
 import { getSocketCacacheDir, getSocketDlxDir } from '../paths/socket'
 import { processLock } from '../process-lock'
@@ -333,8 +335,8 @@ export async function ensurePackageInstalled(
       }
 
       // Install package and dependencies using Arborist (like npx does).
-      // Arborist handles everything: fetching, extracting, dependency resolution, and bin links.
-      // This creates the proper flat node_modules structure with .bin symlinks.
+      // Split into buildIdealTree → firewall check → reify so we can
+      // scan all resolved packages before downloading any tarballs.
       try {
         // Arborist is imported at the top
         /* c8 ignore next 3 - External Arborist constructor */
@@ -356,12 +358,26 @@ export async function ensurePackageInstalled(
           silent: true,
         })
 
-        // Use reify with 'add' to install the package and its dependencies in one step.
-        // This matches npx's approach: arb.reify({ add: [packageSpec] })
+        // Step 1: Resolve dependency tree (registry metadata only, no tarballs).
+        /* c8 ignore next - External Arborist call */
+        await arb.buildIdealTree({ add: [packageSpec] })
+
+        // Step 2: Check resolved packages against Socket Firewall API (public).
+        /* c8 ignore next - External API call */
+        await checkFirewallPurls(arb, packageName)
+
+        // Step 3: Download tarballs and install. Reuses the cached idealTree.
         // save: true creates package.json and package-lock.json at the root (like npx).
         /* c8 ignore next - External Arborist call */
-        await arb.reify({ save: true, add: [packageSpec] })
+        await arb.reify({ save: true })
       } catch (e) {
+        // Rethrow firewall block errors without wrapping.
+        if (
+          e instanceof Error &&
+          e.message.startsWith('Socket Firewall blocked')
+        ) {
+          throw e
+        }
         const code = (e as any).code
         if (code === 'E404' || code === 'ETARGET') {
           throw new Error(
@@ -612,6 +628,122 @@ export function makePackageBinsExecutable(
   }
 }
 
+// ── Socket Firewall API check ──
+
+const FIREWALL_API_URL = 'https://firewall-api.socket.dev/purl'
+const FIREWALL_TIMEOUT = 10_000
+const FIREWALL_BLOCK_SEVERITIES: ReadonlySet<string> = new Set([
+  'critical',
+  'high',
+])
+
+interface FirewallAlert {
+  severity?: string
+  type?: string
+  key?: string
+}
+
+interface FirewallResponse {
+  alerts?: FirewallAlert[]
+}
+
+/**
+ * Build a PURL string for an npm package.
+ * Follows the PURL spec for the npm type:
+ *   - Scoped: `@scope/pkg` → `pkg:npm/%40scope/pkg@version`
+ *   - Unscoped: `pkg` → `pkg:npm/pkg@version`
+ *
+ */
+export function npmPurl(name: string, version: string): string {
+  const encoded = name.startsWith('@') ? `%40${name.slice(1)}` : name
+  // PURL spec: '+' in version must be encoded as %2B
+  const encodedVersion = version.replace(/\+/g, '%2B')
+  return `pkg:npm/${encoded}@${encodedVersion}`
+}
+
+/**
+ * Check all resolved packages in an Arborist ideal tree against the
+ * Socket Firewall API (public, no auth required).
+ * Throws if any dependency has critical or high severity alerts.
+ *
+ * @param arb - Arborist instance with populated idealTree
+ * @param requestedPackage - Top-level package name (for error messages)
+ * @private
+ */
+async function checkFirewallPurls(
+  arb: InstanceType<typeof Arborist>,
+  requestedPackage: string,
+): Promise<void> {
+  const idealTree = arb.idealTree
+  if (!idealTree) {
+    return
+  }
+
+  // Collect PURLs for all non-root resolved nodes.
+  const purls: Array<{ purl: string; name: string; version: string }> = []
+  for (const node of idealTree.inventory.values()) {
+    if (node.isProjectRoot) {
+      continue
+    }
+    const { name, version } = node.package
+    if (!name || !version) {
+      continue
+    }
+    purls.push({ purl: npmPurl(name, version), name, version })
+  }
+  if (purls.length === 0) {
+    return
+  }
+
+  const blocked: Array<{
+    name: string
+    version: string
+    alerts: string[]
+  }> = []
+
+  // Check all PURLs against the public firewall API in parallel.
+  await Promise.allSettled(
+    purls.map(async ({ name, purl, version }) => {
+      try {
+        const data = await httpJson<FirewallResponse>(
+          `${FIREWALL_API_URL}/${encodeURIComponent(purl)}`,
+          {
+            headers: { 'User-Agent': SOCKET_LIB_USER_AGENT },
+            timeout: FIREWALL_TIMEOUT,
+            retries: 1,
+            retryDelay: 500,
+          },
+        )
+        const blocking = (data.alerts ?? []).filter(
+          a => a.severity && FIREWALL_BLOCK_SEVERITIES.has(a.severity),
+        )
+        if (blocking.length > 0) {
+          blocked.push({
+            name,
+            version,
+            alerts: blocking.map(
+              a => `${a.severity}: ${a.type ?? a.key ?? 'unknown'}`,
+            ),
+          })
+        }
+      } catch {
+        // Firewall API errors are non-fatal — allow install to proceed.
+      }
+    }),
+  )
+
+  if (blocked.length > 0) {
+    const details = blocked
+      .map(b => `  ${b.name}@${b.version}: ${b.alerts.join(', ')}`)
+      .join('\n')
+    throw new Error(
+      `Socket Firewall blocked installation of "${requestedPackage}".\n` +
+        `The following dependencies have security alerts:\n${details}\n\n` +
+        'Visit https://socket.dev for more information.',
+    )
+  }
+}
+
 /**
  * Parse package spec into name and version using npm-package-arg.
  * Examples:

src/external/@npmcli/arborist.d.ts

@@ -1,4 +1,19 @@
 declare namespace ArboristTypes {
+  export interface ArboristNode {
+    package: {
+      name?: string
+      version?: string
+      [key: string]: unknown
+    }
+    isProjectRoot: boolean
+    name: string
+    location: string
+  }
+
+  export interface IdealTree {
+    inventory: Map<string, ArboristNode>
+  }
+
   export interface Options {
     path?: string
     cache?: string
@@ -7,18 +22,23 @@ declare namespace ArboristTypes {
   }
 
   export interface BuildIdealTreeOptions {
+    add?: string[]
     [key: string]: unknown
   }
 
   export interface ReifyOptions {
     save?: boolean
+    add?: string[]
     [key: string]: unknown
   }
 }
 
 export default class Arborist {
+  idealTree: ArboristTypes.IdealTree | null
   constructor(options?: ArboristTypes.Options)
-  buildIdealTree(options?: ArboristTypes.BuildIdealTreeOptions): Promise<void>
+  buildIdealTree(
+    options?: ArboristTypes.BuildIdealTreeOptions,
+  ): Promise<ArboristTypes.IdealTree>
   reify(options?: ArboristTypes.ReifyOptions): Promise<void>
 }
 

src/http-request.ts

@@ -16,6 +16,7 @@
 
 import type { Readable } from 'node:stream'
 
+import { SOCKET_LIB_USER_AGENT } from './constants/socket'
 import { safeDelete } from './fs.js'
 
 let _fs: typeof import('node:fs') | undefined
@@ -1161,7 +1162,7 @@ async function httpRequestAttempt(
       : undefined
 
   const mergedHeaders = {
-    'User-Agent': 'socket-registry/1.0',
+    'User-Agent': SOCKET_LIB_USER_AGENT,
     ...streamHeaders,
     ...headers,
   }