Package Proxy

What is Package Proxy?

Package Proxy is a paid boring.tools feature that sits in front of the public npm registry. It does not replace npm and it is not a private registry. Instead, it forwards allowed npm metadata and tarball requests to the upstream registry while adding policy checks and install audit records.

Use it when you want to know and control:

• which npm packages are installed by a project,
• which developer machine, CI job, or automation source installed them,
• whether unknown packages should only be monitored or blocked,
• which packages were requested as metadata versus tarballs.

How it works

1. Create a source token for CI, a developer, automation, or a shared product install source.
2. Link the token to one or more projects.
3. Configure npm to use your Package Proxy URL with that token.
4. Start in monitor mode to collect install audit events without blocking builds.
5. Seed an allowlist from the latest SBOM components for the linked projects.
6. Switch to allowlist mode when you are ready to block unknown packages.

Deny rules always win over allow rules. Organization-wide rules apply to every linked project. Project rules apply only when the source token is linked to that project.

Configure npm

In the boring.tools app, open Organization settings → Package Proxy, create a source token, and copy the generated .npmrc snippet.

The snippet has this shape:

registry=$PACKAGE_PROXY_PUBLIC_URL/npm/<org-slug>/
//$PACKAGE_PROXY_PUBLIC_HOST/npm/<org-slug>/:_authToken=btp_...
always-auth=true

For CI, store the token as a masked secret and write .npmrc at build time:

cat > .npmrc <<'EOF'
registry=$PACKAGE_PROXY_PUBLIC_URL/npm/<org-slug>/
//$PACKAGE_PROXY_PUBLIC_HOST/npm/<org-slug>/:_authToken=${PACKAGE_PROXY_TOKEN}
always-auth=true
EOF

Do not commit real source tokens to your repository.

Monitor mode vs allowlist mode

Monitor mode

Monitor mode forwards installs even when no matching allow rule exists. It records audit events so you can see which packages a source would need before enforcing policy.

Use monitor mode during rollout:

• first CI run after adding Package Proxy,
• project onboarding,
• dependency update windows,
• diagnosing missing allow rules.

Allowlist mode

Allowlist mode blocks unknown packages with 403. A package is allowed when at least one linked project or organization-wide rule matches the package. Deny rules override allow rules.

Switch to allowlist mode after seeding and reviewing the initial rules.

Seed allowlists from SBOMs

If your projects already have SBOMs in boring.tools, Package Proxy can seed allow rules from the latest known SBOM component set.

Recommended rollout:

1. Upload or generate SBOMs for the projects linked to the source token.
2. Select those projects in the Package Proxy UI.
3. Click Seed allowlist from latest SBOMs.
4. Review the generated rules.
5. Keep monitor mode for at least one build.
6. Switch to allowlist mode.

Source token types

A token can be linked to multiple projects. This is useful when one product is assembled from multiple repos or when shared utilities are installed together with project-specific code.

Caching

Package Proxy can cache npm metadata and tarballs. Caching is not required for policy or audit, but it improves repeated installs and reduces direct dependency on the upstream registry.

Production deployments should use Redis as the cache backend:

PACKAGE_PROXY_CACHE_BACKEND=redis
REDIS_URL=redis://redis:6379
PACKAGE_PROXY_CACHE_MAX_BYTES=52428800
PACKAGE_PROXY_METADATA_CACHE_TTL_SECONDS=300
PACKAGE_PROXY_TARBALL_CACHE_ENABLED=true

Large artifacts over PACKAGE_PROXY_CACHE_MAX_BYTES are forwarded but not cached. Memory cache is intended for development or small single-instance setups only.

Audit data

Package Proxy records install audit events for metadata and tarball requests. Events include the source token, linked projects, package name, request type, policy decision, status code, and remote IP.

Remote IP is stored raw for auditability. If you self-host boring.tools, make sure your privacy notice and retention policy cover this data.

Self-hosting configuration

Set one public URL for the Package Proxy deployment:

PACKAGE_PROXY_PUBLIC_URL=https://pkg.example.com

The app frontend reads the same value through runtime config, so self-hosted deployments do not need to rebuild the frontend just to change the registry host.

For reverse proxies, route that host to the registry-proxy service on port 4010 and make sure TLS is configured before using it in npm.

Troubleshooting