Architecture

nproxy is a transparent proxy that sits between your package manager and upstream registries (npm, PyPI, Go, Cargo, Maven, RubyGems). It requires no agents, sidecars, or changes to your development workflow.

Request flow

Developer                      nproxy                         npm registry
   |                             |                               |
   |  npm install express        |                               |
   |  ─────────────────────>     |                               |
   |                             |  GET /express                 |
   |                             |  ────────────────────────>    |
   |                             |                               |
   |                             |  <packument>                  |
   |                             |  <────────────────────────    |
   |                             |                               |
   |                        ┌────┴─────┐                         |
   |                        │  Apply   │                         |
   |                        │  Rules   │                         |
   |                        └────┬─────┘                         |
   |                             |                               |
   |  <filtered packument>       |                               |
   |  <─────────────────────     |                               |

Your package manager sends requests to your nproxy endpoint (e.g. https://your-org.nproxy.app/ for npm, /pypi/simple/ for PyPI, /go/ for Go, and similar paths for Cargo, Maven, and RubyGems)
nproxy fetches the package metadata from the upstream registry
All enabled security rules evaluate every version
Blocked versions are stripped before the response reaches your package manager
Your package manager resolves to the latest safe version automatically

Request types

Type	What happens
Package metadata (GET)	Fetched from upstream, filtered by security rules, returned to client
Tarball download (GET)	Proxied from upstream (or served directly for internal packages)
Git tarball (GET)	Fetched from GitHub's archive API, cached permanently. Supports SHA-pinned installs via `/-/git/` path prefix. See Git SHA Installs.
npm audit (POST)	Intercepted and enriched with OSV.dev vulnerability data, synthetic advisories injected
Publish (PUT)	Internal packages are stored securely and signed with the org's Ed25519 key. Public packages are forwarded to the upstream npm registry.
Signing keys (GET)	Returns the org's public signing keys at `/-/npm/v1/keys`
Whoami (GET)	Returns your nproxy identity if using an nproxy token, or forwards to upstream npm
Everything else	Forwarded to the upstream npm registry (login, search, dist-tags, access, teams, orgs, tokens, profile, etc.)

Organizations and tenants

Each organization gets a dedicated proxy endpoint at https://<slug>.nproxy.app/. Configuration changes (rule settings, tokens, auth requirements) take effect immediately — no deploy or restart needed.

Authentication

nproxy supports two types of bearer tokens:

nproxy tokens (nproxy_ prefix) -- Validated against the organization's token manifest. Used for proxy authentication, internal package operations, and identity (npm whoami).
npm tokens (npm_ prefix or other) -- Forwarded to the upstream npm registry as-is. Used for npm operations like npm publish, npm login, npm deprecate, and other write operations against public npm.

When forwarding requests to the upstream npm registry, nproxy strips nproxy_ tokens (which npm would not accept) and preserves any other tokens.

Additional auth controls:

If requireToken is enabled, unauthenticated read requests are rejected (upstream tokens are allowed through for write/management operations)
If mTLS is enabled (Enterprise), client certificates are also validated
Rate limiting is applied per IP address (600 requests per minute)

Code signing

nproxy supports Ed25519 code signing with a configurable enforcement spectrum:

Policy	Internal packages	Public packages
`off`	Not signed	Not attested
`warn`	Signed at publish, missing sigs warned	Attested on first pass, missing attestations warned
`internal`	Signed at publish, missing sigs blocked	Not attested
`all`	Signed at publish, missing sigs blocked	Attested on first pass, missing attestations blocked

Internal packages are signed automatically at publish time with the org's Ed25519 private key (which never leaves the Durable Object). Public packages are co-signed (attested) by nproxy as they pass through and survive security rules. Signatures use npm's standard dist.signatures format.

Code signing is available on all plans.

Fail-open design

nproxy is designed to never block legitimate work due to an infrastructure issue. If a threat intelligence service is temporarily unavailable, rules that depend on it skip rather than block all packages.

Response headers

Every proxy response includes headers that tell you what happened:

Header	Description
`x-nproxy-tenant`	Your organization slug
`x-nproxy-blocked`	Number of versions removed
`x-nproxy-warned`	Number of warn-level rule triggers
`x-nproxy-traffic-source`	Traffic source classification (`human`, `agent`, `ci`, `unknown`)
`x-nproxy-packument-cache`	Packument cache status (`hit`, `stale`, `miss`, `bypass`)
`x-nproxy-signing`	Signature verification status (`verified`, `attested`, `warn`, `off`)
`x-nproxy-source`	Source of the package (`git` for git SHA installs)

MCP server

The nproxy MCP server exposes proxy data to AI coding agents. Agents can query the audit log, check package scores, and review rule decisions from within an IDE or agent framework. See the MCP server docs for setup instructions.

Package bindings

nproxy can optionally treat sensitive environment variables as explicit package-manager and production runtime capabilities. In observe and warn modes, env vars continue to pass through unchanged. In enforce mode, managed commands only receive sensitive env vars that have a matching binding grant. See Package Bindings.

Cross-org trust signals

nproxy tracks a package_adoption table that records which packages are installed across organizations. When an organization installs a package that other nproxy tenants already use, this cross-org adoption signal feeds into rule evaluation -- packages widely adopted by other nproxy organizations carry higher trust than packages seen for the first time.