Open-source engineering tool by Mirasen

Mirasen License Gate

A strict, local, default-deny license policy gate for npm projects — single package, workspaces, and monorepos.

Overview

Strict by design

License Gate reads what is physically installed and enforces a local allowlist you control. It refuses to guess, and it makes every exception visible.

Local & literal

License Gate reads what is physically installed via @npmcli/arborist and compares each package’s license string verbatim against your allowlist. Apache 2.0 is not Apache-2.0. It does not guess, infer, or normalise.

Escape hatches, visible

Overrides live in licenses/allowed-packages.txt. They are allowed, but every matched override is surfaced in the report as matchedPackageRule — never a silent exclude.

Quick start

Install and run

Run it after npm ci. Unknown or unapproved license strings fail the build.

        npm install -D @mirasen/license-gate
mkdir -p licenses
echo "MIT" > licenses/allowed-hard.txt
npx license-gate check

Requires Node.js ≥ 22.9.0.

See the README for the full command reference.

How it works

Policy model

License Gate reads the installed dependency graph via @npmcli/arborist. Each package’s license string is checked verbatim against licenses/allowed-hard.txt. SPDX expressions are parsed only to enumerate leaves, and each leaf is then checked literally — everything not explicitly allowed is a violation. Packages whose license cannot be determined need an explicit entry in licenses/allowed-packages.txt, and every matched override stays visible in the report as matchedPackageRule.

check collect --workspace --cwd --json

Install @mirasen/license-gate as a dev dependency.
Add licenses/allowed-hard.txt with one license per line.
Run license-gate check after npm ci.

Scope boundaries

What it will not do

These are intentional boundaries, not gaps. Strictness is the point.

No license file reading

LICENSE, COPYING, and README are never opened.

No license normalization

Apache 2.0 is not the same as Apache-2.0.

No project-root walk-up

--cwd is the only way to change the project root.

No silent excludes

Every package the gate considered is accounted for in the report.

npm-first scope

The tool is intentionally scoped to npm-installed graphs. pnpm, yarn, Gradle, and Maven are out of scope.

Links

Use it from npm or inspect the source

Install the package from npm, review the README for the full command reference, or inspect the repository before adding it to CI.

Repository Package Changelog