Registry formats · npm
Publish your scoped packages, proxy and cache
registry.npmjs.org, and serve
both from one URL in your .npmrc.
OrbitalReg's npm
format speaks the npm registry API, checks every tarball against advisories,
answers npm audit itself,
and can steer version ranges away from releases with known advisories,
inside the same self-hosted registry that holds your images, charts and
other packages.
One file to change
.npmrc at your registry.
Every repository lives at /npm/<project>/<repo>/.
Point the default registry at a virtual repo that federates your
internal packages with a cached npmjs remote, and add one
@scope:registry line
for each scope you publish.
Coming from Verdaccio or another private npm registry? Same wire format, so the migration is largely a registry-URL change. Keep the public-registry remote in your virtual repo during the cutover and consumers won't notice.
# .npmrc: one URL for internal and public packages
registry=https://registry.example.com/npm/acme/all-libs/
//registry.example.com/npm/acme/all-libs/:_authToken=$ORBITALREG_TOKEN
//registry.example.com/npm/acme/all-libs/:always-auth=true
# scoped packages get their own line
@acme:registry=https://registry.example.com/npm/acme/internal/
//registry.example.com/npm/acme/internal/:_authToken=$ORBITALREG_TOKEN# publish: tarball validated, sha-512 integrity computed on write
$ npm publish --registry=https://registry.example.com/npm/acme/internal/
# audit is answered by the registry's own OSV-synced advisory table
$ npm auditSafe-version delivery
Turn it on for a virtual npm repo and versions that an advisory
definitely affects disappear from the package document, but only
when a clean replacement exists inside the range you allow:
same major.minor in patch mode, same major in
minor mode. ^1.2.0
with a vulnerable 1.2.3 and a clean 1.2.4 installs 1.2.4, and any
dist-tag that pointed at the removed version moves with it.
What it never does is swap bytes under a lockfile. An exact request for a blocked tarball still gets a 403, because silently serving something other than what the lockfile names would break reproducibility and integrity checks. Every redirect is recorded in the audit log and announced in a response header. Off by default.
# virtual repo, safe-version: patch
GET /npm/acme/all-libs/example-lib
"versions": {
"1.2.2": { … },
"1.2.3": { … } ← advisory affects 1.2.3: hidden
"1.2.4": { … } ← clean, same major.minor
},
"dist-tags": { "latest": "1.2.4" }
X-OrbitalReg-Remediated-From: 1.2.3->1.2.4# a lockfile that pins the vulnerable version is never rewritten
GET /npm/acme/all-libs/example-lib/-/example-lib-1.2.3.tgz
HTTP/1.1 403 → the block page explains whyWhat you get
OrbitalReg's npm adapter implements the npm registry HTTP API: npm publish, npm install, scoped packages and dist-tags (add, rm, ls). Because the wire format is the registry's own, npm, pnpm and Yarn need nothing but a registry URL in .npmrc.
Local repos take your internal packages via npm publish. Remote repos proxy and cache registry.npmjs.org. A virtual repo federates both behind one URL (first match wins per package version), so one registry line covers internal and public dependencies.
Every published tarball is validated, its package.json extracted for metadata, and a sha-512 integrity digest computed, the value npm's lockfile expects. Then artifact and metadata are written in a single transaction.
Each upload gets an SBOM (Syft) matched against OSV.dev advisories; Trivy and Grype add deep scans for the projects you enable them on. Findings above a project's threshold quarantine the version: it stays visible for triage but answers downloads with HTTP 451 and a why-blocked explanation.
npm audit talks to the registry itself: the bulk-advisory endpoint answers from OrbitalReg's own OSV-synced advisory table, so npm audit keeps working where clients cannot reach registry.npmjs.org. Only the registry needs the advisory feed.
When a tarball ships an SLSA provenance attestation, OrbitalReg parses it, verifies the embedded Sigstore signature against your configured trust policy, and keeps the verified provenance next to the artifact for audit.
Optional and off by default: a policy engine evaluated before every serve can block on maximum CVE severity, licence allow- or deny-lists, a missing SBOM or signature, or on your own Rego rules, and answers with a 403 whose X-Orbital-PullGate-* headers explain the reason even to CI runners that drop the body.
Retention rules can keep every version a dist-tag points at (latest, next) plus the N newest, and prune the rest. Pruned versions sit in Trash for 30 days before the object is deleted.
Why not an npm-only registry
Verdaccio is a good, lightweight, open-source answer to "host our
private npm packages and cache the public ones." If that is the
whole job, it does it well. What it doesn't do is scan the tarballs
it caches, quarantine a version when an advisory lands, block a
known-malicious package by name or hash, or hold the container
image, Helm chart, PyPI and Maven packages your application ships
alongside its node_modules.
In OrbitalReg the npm format is one GA adapter among 40+, governed
by the same projects, roles, retention policies and append-only audit
log, with the security layer in the
free version.
Why that matters for npm specifically is documented in the ChainDrop / keyv worm, Shai-Hulud and node-ipc case studies. Coming from Artifactory's npm repositories instead? The migration page covers the cutover, and the pricing comparison puts JFrog's published tiers next to ours.
Questions
Set registry= in .npmrc to your repo URL (https://<host>/npm/<project>/<repo>/) and add an _authToken line for the same host path. Scoped packages need their own @scope:registry= line. npm, pnpm and Yarn all read .npmrc, so nothing else changes in your toolchain.
Yes. A remote npm repository proxies and caches https://registry.npmjs.org. Put it behind a virtual repository together with your local repo and developers use one URL for internal and public packages. In air-gapped deployments, upstream pulls are blocked unless egress is explicitly allowed per remote repo.
An optional policy on virtual npm repositories. When it is on, versions an advisory definitely affects are hidden from the package document if a clean replacement exists within the allowed range (same major.minor in patch mode, same major in minor mode), so a range like ^1.2.0 resolves to the clean 1.2.4 instead of the vulnerable 1.2.3. Exact pins are never rewritten: a lockfile that names 1.2.3 gets a 403, because serving different bytes than the lockfile names would break integrity checks.
For hosting private packages and caching the public registry, yes. And because Verdaccio and the npm registry share the same wire format, migrating is largely a registry-URL change. The difference is scope: Verdaccio is a lightweight, open-source npm-only registry, while OrbitalReg is one self-hosted registry for 40+ formats that also scans every tarball, quarantines vulnerable versions and can gate installs on policy.
Create a security block. A package block matches the package name as a path segment (for example lodash), a pattern block matches a glob for one specific version, and a sha256 block matches the exact tarball bytes. Blocks fire on every download path, and a developer whose npm install was refused gets a public /blocked page with your message.
They use the same registry protocol and read the same .npmrc settings, so they install from an OrbitalReg npm repository the same way npm does.
Documentation: npm format reference · safe-version delivery · pull-gate · format support matrix · air-gapped operations
Free forever · no contract
One Helm chart, one Go binary, Postgres and S3-compatible storage. Scanning, quarantine and pull-gates are part of the free version.