ChainGate Runtime

Run checks in the npm install path.

A local proxy and CLI that compare npm release metadata with recorded history. Inspect the reasons behind a result and control which releases your project accepts.

npm ecosystem
Node.js 22 or 24
Apache-2.0

View repository Installation guide

Research prototype. It evaluates metadata, not the code inside a package.

Default proxy checks

No v3 seed is required. On a new setup, chaingate init prepares a writable witness store, starts the proxy and points npm at it. It normally downloads a signed legacy witness seed; --no-seed starts with an empty store. Neither enables v3 detection.

An empty store starts without comparison coverage: five checks SKIP below eight prior versions; the hash check needs a prior observation of the same version with comparable hashes. See the evidence requirements.

Try the CLI today

npm: 0.1.2 published · Source: 0.1.3 candidate

$ npm install -g @cgsec/chaingate@0.1.2

$ chaingate --help

For saved-result inspection, use the downloadable JSON example: no active seed or fresh evaluation is needed. On npm 12, the native SQLite dependency needs explicit script approval; follow the installation guide.

Before a v3 evaluation

The opt-in proxy v3 check and the CLI’s check --packument / why --packument paths require a locally supplied, active v3 detection seed and configured policy. No public v3 seed download is available yet.

The current seed candidate is unsigned: importing it requires --unsigned-development and it remains unauthenticated. Installing the CLI or a legacy witness seed does not enable v3. Fresh-evaluation command.

Reproduced from a public test fixture

A warning with a reason.

Fixture source

Synthetic package `p@1.6.0`

The test seed retains 1.0.0, 1.1.0, and 1.2.0. The candidate appends to that release line.

Fixture metadata: prior release and candidate
Field	1.2.0	1.6.0
Install script	None	`postinstall` added
Unpacked size	1,000 bytes	9,000 bytes
Provenance	Present	Present

Two trajectory checks fire: an install script appears and size grows beyond the 5× threshold. The effective action is WARN; no advisory pins this fixture version.

This is a synthetic test package, not a registry observation or incident. The result demonstrates implemented behavior, not maliciousness.

Actual fixture explanation · excerptWARN

p@1.6.0: WARN
  evaluated disposition: WARN under cft-policy-1.0
  placement: append
  decided by:
    seed-v3:dac-trajectory:surface: 2/4 witnesses broke, threshold 2 (threshold over history: warns, never blocks — D1)
    seed-v3:dac-trajectory:any: 2/4 witnesses broke, threshold 1 (threshold over history: warns, never blocks — D1)
  …
  dac trajectory predicates:
    install_introduced: BROKE
    size_jump_5x: BROKE
    prov_dropped: held
    first_pkg_appearance_new_publisher: held

Download the full resultJSON · schema chaingate.check/1

Generated from Runtime 0.1.2 source 56d0e7c, using its unchanged warn-trajectory fixture and policy. Verified with the published CLI. The fixture seed is intentionally unsigned.

Inspect this result locally

Save the download as runtime-example.json, then run this command. It reads the saved record without fetching metadata or evaluating again, and needs no active seed.

$ chaingate why --from ./runtime-example.json

What Runtime checks

The proxy enables six built-in checks. V3 seed evaluation is added when a detection seed is configured.

Proxy defaults and evidence requirements
Check	Proxy default	Evidence required	Result and missing evidence
Content hash	On	A prior observation of the same package and exact version, with comparable integrity or shasum fields.	BLOCK when the recorded hash changes. SKIP on first sight or when hashes cannot be compared.
Dependency structure	On	Runtime dependency names across prior observed versions.	WARN for a dependency name absent from that history. No declared runtime dependencies returns ALLOW.
Publisher identity	On	Publisher email on the incoming release and the latest prior observation.	WARN on a changed email. SKIP when either identity is missing.
Provenance continuity	On	At least one prior observed version with provenance.	WARN when provenance is absent after previously being present. SKIP without a provenance baseline.
Release age	On	A parseable publication time. Default cooldown: 72 hours.	WARN inside the cooldown; prereleases are exempt. SKIP when publication time is missing.
Scope boundary	On	New runtime dependencies together with install scripts; cached dependency publication times add context.	WARN for that combination, including when dependency age is unknown. This check does not BLOCK.
V3 seed evaluation	Opt-in	An active detection seed: release lineages, retained changes, and exact-version advisory pins.	History-based signals WARN; a recorded advisory pin can BLOCK. Unavailable comparisons report NOT_EVALUATED and follow the configured policy.

The five history-based built-ins SKIP until at least 8 prior versions are observed. Content hash and v3 evaluation are exempt from that local-history threshold. Content hash compares repeated observations of the same exact version; different hashes across different releases are expected.

Source: default check runner, individual checks, and proxy wiring. The CLI’s check --packument uses the v3 evaluation path; it is not a run of all six proxy checks.

Read the result, then the coverage.

These are the effective actions and exit codes from check. Successfully explaining a saved result with why --from exits 0, even when the recorded action is WARN or BLOCK.

ALLOW 0: The effective action permits the release. It is not a guarantee that its code is safe.
WARN 2: The release is permitted with a recorded warning or evidence gap.
BLOCK 3: The effective action refuses the release. Read the reason to distinguish a recorded fact from an input-policy refusal.
Tool error 4: The command could not produce a usable decision, or was used to inspect a legacy unbound record.

Missing evidence and overrides

Built-in checks that cannot run return SKIP; SKIP does not raise the aggregate action. V3 explicitly marks unavailable comparisons as NOT_EVALUATED. An unconfigured missing-evidence policy refuses to decide.

V3 setup records choices for unusable input (BLOCK or WARN) and no evidence (WARN or ALLOW). A valid proxy setup requires those choices.

An exact-version override permits the release. The CLI preserves the evaluated disposition beside the overridden effective action; the proxy short-circuits its checks for an overridden version.

Limitations

Published 0.1.2 evaluates metadata requests. Tarball requests use stored decisions; a lockfile install can bypass a fresh metadata evaluation. Requests must pass through the proxy for enforcement to apply.

The 0.1.3 source candidate adds evaluation before serving previously unevaluated tarballs, and advisory-pin checks on unusable-input paths. These changes are not in the npm package shown above. Its failure behavior still depends on configured policy.

Candidate enforcement and failure behavior

Fresh v3 evaluation

With an active v3 seed and configured policy, provide a local registry metadata file for the named release. Replace the placeholders with your package, version and file. This evaluates afresh and writes the result to check.json.

Inspect a saved result: use the fixture example

$ chaingate check <package>@<version> --packument ./packument.json --json > ./check.json

Legacy cached-result reference

why <package>@<version> --cached displays stored rows without seed, rule or policy identity. It labels them CACHED — UNBOUND and exits 4. Command implementation.