Dependency checks

The deps gate of mainsdk check flags made-up, brand-new and look-alike packages, advisories, denied licences and unreviewed install scripts in your dependencies. It runs in the CLI only and is free.

deps:
  min-age: 7d                    # a direct dependency first published more recently is reported
  licences: { deny: [AGPL-3.0-only, SSPL-1.0], allow: [], unknown: warn }
  advisories:
    fail-on: high                # critical | high | moderate | low | none
    ignore:
      - { id: GHSA-xxxx-xxxx-xxxx, until: 2027-01-31, reason: "Not reachable: only used in tests" }
  scripts: { allow: [esbuild, sharp] }
  offline: info                  # info | fail

# mainsdk check runs the deps gate with the others; the CLI asks the registry and OSV, then keeps the answers for 24 hours
npx mainsdk check --json

deps:
  driver: osv

Quick start

npx mainsdk check

The gate needs no setting. mainsdk check asks the registry and OSV.dev once, keeps the answers for 24 hours under .mainsdk/cache/deps/, and then runs every gate.

Configuration

Add a deps section to main.yaml to change the policy. Every key is optional.

deps:
  min-age: 7d                    # a direct dependency first published more recently is reported
  licences:
    deny: [AGPL-1.0-or-later, AGPL-3.0-only, AGPL-3.0-or-later, SSPL-1.0]   # the default list
    allow: []                    # when not empty, any licence outside it is reported
    unknown: warn                # warn | fail
  advisories:
    fail-on: high                # critical | high | moderate | low | none
    ignore:
      - { id: GHSA-xxxx-xxxx-xxxx, until: 2027-01-31, reason: "Not reachable: only used in tests" }
  scripts:
    allow: [esbuild, sharp]      # packages allowed to run install scripts
  offline: info                  # info | fail; fail is for CI with network access

What you get

The deps gate of mainsdk check reads your lockfile and the installed packages and tells you, before CI or a deploy does, that a dependency is a name a model made up, was published two days ago, is one letter from a popular package, has a known advisory, carries a licence you can't ship under, or runs an install script nobody allowed. Every finding names the package, the version, why and the fix. It runs in the CLI only: nothing of it loads in your app or its request path. It is free.

What it reads

• Lockfiles: pnpm-lock.yaml (v9), package-lock.json (v3), yarn.lock (classic and Berry) and bun.lock. Every format gives the same list: name, version, direct or transitive, and the path from a direct dependency. Workspace packages are left out.
• Direct dependencies: the dependencies, devDependencies, optionalDependencies and peerDependencies of every workspace package.json.
• Registries: the registry and @scope:registry lines of .npmrc (project, then user), else the public npm registry. A token goes only to the host it is configured for, never to another registry and never to OSV.
• Installed packages: each node_modules/<name>/package.json (and pnpm's store) for the licence and install scripts. A package that isn't installed has no licence or script finding.

Offline and the cache

With no network and no cache younger than 24 hours, the gate reports MAIN-DEPS-0007 once and still runs the lockfile, licence and script rules. An unreachable registry or OSV never blocks a local check; after the first failure the CLI stops asking, so an offline run costs one timeout. Set offline: fail in CI, where the network is there.

What it always does

• Runs only in the CLI, never in the app (ADR-0074).
• Sends no credentials to OSV, and registry tokens only to their own host.
• Gives the same component list for the same dependencies in any lockfile format.

Errors and checks

Each code's cause and fix is in check codes.

Swapping drivers

deps has no driver. It runs in the CLI against your lockfile, the registry and OSV.dev, so there is nothing to swap.

Testing

The gate's tests run against a fake registry, a fake private registry and a fake OSV server, so none reaches a real host (packages/cli/test/deps.test.ts). In your own CI, run npx mainsdk check with offline: fail so a missing network fails the build.

Next

• Check your dependencies
• Check codes