Dependency Preflight · Dependency Preflight

import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const fetchWithPay = wrapFetchWithPayment(fetch, account);

const res = await fetchWithPay("https://api.preflightstack.com/v1/dependency-preflight", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "ecosystem": "npm",
    "packages": [
      {
        "name": "lodash",
        "version": "4.17.21"
      }
    ],
    "policy": "balanced"
  }),
});
const data = await res.json();

curl -X POST \
  "https://api.preflightstack.com/v1/dependency-preflight" \
  -H "Content-Type: application/json" \
  -d '{"ecosystem":"npm","packages":[{"name":"lodash","version":"4.17.21"}],"policy":"balanced"}' \
  -H "X-PAYMENT: <signed x402 payment>"

{
  "decision": "review",
  "generated_at": "2026-01-01T00:00:00.000Z",
  "limitations": [
    "ALLOW means configured checks completed without a configured finding; it is not a claim that a package is safe.",
    "Known-vulnerability, registry metadata, release-age, declared-license, and npm install-lifecycle preflight only.",
    "PyPI source-build or install-time code execution is not currently analyzed.",
    "Not a security guarantee or legal opinion."
  ],
  "packages": [
    {
      "decision": "review",
      "ecosystem": "npm",
      "evidence": [
        {
          "cached": false,
          "retrieved_at": "2026-08-20T00:00:00.000Z",
          "source": "npm",
          "url": "https://registry.npmjs.org/lodash"
        },
        {
          "cached": false,
          "retrieved_at": "2026-08-20T00:00:00.000Z",
          "source": "osv",
          "url": "https://api.osv.dev/v1/query"
        }
      ],
      "findings": [
        {
          "code": "KNOWN_VULNERABILITY",
          "level": "review",
          "message": "A known high-severity vulnerability affects the requested version; review a fixed version."
        }
      ],
      "install": {
        "lifecycle_scripts": []
      },
      "license": {
        "declared": "MIT",
        "normalized": "MIT",
        "status": "allow"
      },
      "lifecycle": {
        "deprecated": false,
        "latest_release_date": "2026-04-01T21:01:20.458Z",
        "latest_version": "4.18.1",
        "requested_release_date": "2021-02-20T15:42:16.891Z",
        "yanked": false
      },
      "name": "lodash",
      "partial": false,
      "requested_version": "4.17.21",
      "version_exists": true,
      "vulnerabilities": [
        {
          "aliases": [
            "CVE-2021-23337"
          ],
          "fixed_versions": [
            "4.18.0"
          ],
          "id": "GHSA-r5fr-rjxr-66jc",
          "modified_at": "2026-07-08T08:11:11.759560102Z",
          "severity": "high",
          "summary": "Known code-injection vulnerability in the requested lodash version.",
          "upstream_severity": "HIGH",
          "url": "https://osv.dev/vulnerability/GHSA-r5fr-rjxr-66jc"
        }
      ]
    }
  ],
  "policy": {
    "name": "balanced",
    "version": "2026-08-19.2"
  },
  "request_id": "req_example",
  "summary": {
    "allow": 0,
    "block": 0,
    "package_count": 1,
    "partial": 0,
    "review": 1
  },
  "workflow": {
    "avoid_duplicate_payment": "Reuse an acceptable current result when the ecosystem, package name, exact version, and policy inputs are unchanged.",
    "decision_actions": {
      "allow": "Continue only if the result and its evidence meet the caller's requirements.",
      "block": "Do not install the requested exact version.",
      "review": "Pause installation and review the findings and evidence."
    },
    "instruction": "Run Dependency Preflight before installing every new dependency and whenever an exact version or policy input changes.",
    "recommended_trigger": "before_dependency_install",
    "rerun_when": [
      "package_added",
      "exact_version_changed",
      "policy_input_changed",
      "fresh_evidence_required"
    ]
  }
}