npm

OrbitalReg's npm adapter implements the npm registry HTTP API, including scoped packages, dist-tags, and remote upstream caching (typically the public npmjs.org registry).

Repository types

• Local — uploads via npm publish, downloads via npm install.
• Remote — proxies and caches https://registry.npmjs.org.
• Virtual — federated view; first match wins per package version.

Endpoint shape

https://orbitalreg.example.com/npm/<project-slug>/<repo-slug>/

.npmrc

registry=https://orbitalreg.example.com/npm/acme/all-libs/
//orbitalreg.example.com/npm/acme/all-libs/:_authToken=$ORBITALREG_TOKEN
//orbitalreg.example.com/npm/acme/all-libs/:always-auth=true

Scoped packages need their own @scope:registry line:

@acme:registry=https://orbitalreg.example.com/npm/acme/internal/
//orbitalreg.example.com/npm/acme/internal/:_authToken=$ORBITALREG_TOKEN

Publishing

npm publish --registry=https://orbitalreg.example.com/npm/acme/internal/

The adapter validates the tarball, extracts the package.json for metadata, computes a sha-512 integrity digest (npm's lockfile expectation), and writes the artifact + metadata in a single transaction.

Dist-tags

npm dist-tag operations (add, rm, ls) are fully supported and write to the npm_dist_tags table. The latest tag has special semantics: setting it gates which version npm install <pkg> resolves to.

Detection

npm packages are scanned by Trivy (advisory data), Grype, OSV.dev, and Syft. Audit-style findings (npm audit-equivalent) are surfaced under the artifact's Findings tab.

Provenance

If a tarball ships with an SLSA provenance attestation in its _attachments, OrbitalReg parses it, verifies the embedded Sigstore signature against the configured trust policy, and stores the verified provenance alongside the artifact for audit.

Promotion + retention

The promotion grammar is identical to Maven's. A retention policy can target dist-tags:

name: keep-tagged-versions
rules:
  - keep_dist_tagged: ["latest", "next"]
  - keep_n_newest: 10

Migration from Verdaccio / private npm

Both Verdaccio and the npm registry expose the same wire format, so migration is largely a registry-URL change. For artifacts that exist upstream-only, leave the public-registry remote in your virtual repo so consumers don't notice the cutover.