Client operations

A firewall endpoint speaks the package ecosystem's own protocol, so your existing clients work without a plugin or a wrapper. It implements the part of that protocol that moving packages requires. This page is what that covers.

What the firewall is for

The firewall sits between your clients and your upstream registries and repository managers. Everything it implements serves the three things a package manager asks a registry for:

• Which versions of this package exist. The version list a client resolves against.
• The file for one version. The artifact download.
• Take this file I am publishing. The upload, sent to the upstream you nominate as the publish target.

Each one is a firewall execution phase, so your rules apply to all three. Which client commands work follows from that, and so does which ones do not.

Operations by ecosystem

Every ecosystem resolves versions and downloads artifacts. The other rows differ because the protocols themselves differ, so the table separates two cases:

• n/a: the ecosystem's repository protocol defines no such operation, so there is nothing for a client to ask a firewall endpoint for. The Go module proxy is read-only and has no upload call at all; unlisting, vulnerability data, and search belong to the npm and NuGet protocols rather than to every ecosystem.
• no: the operation exists in the protocol and the firewall does not answer it. Conda publishing is out of scope while Conda support is in beta.

An ecosystem can still publish the same information through a service that sits outside its repository protocol, as pkg.go.dev, search.maven.org, and PyPI's JSON API do. A package manager does not reach those through a firewall endpoint, and routing your clients through a firewall leaves them as they were.

Two of the yes cells carry a caveat on their ecosystem page: npm audit is answered by npmjs.org rather than by your upstreams, and NuGet search results are not policy-filtered, so a blocked version can be listed without being installable.

Publishing also needs a publish target on the firewall. Without one the firewall is install-only and rejects publishes, which is a setting rather than a limit.

What the firewall does not implement

A registry does more than serve packages. It also holds user accounts, issues tokens, and answers search queries. None of that fetches or pushes a package, so there is nothing in it for a firewall to decide: no version to resolve, no artifact to check, no rule that could apply. Account, token, and discovery requests are outside what a firewall endpoint implements, and they return 404.

Discovery sits outside it because you choose a package on the upstream's own site, before it enters your project. Policy belongs where the package is resolved and downloaded, which is what the table above covers. NuGet is the exception, and only because its clients browse the feed itself.

Accounts and tokens sit outside it because identity is not registry-side here. A client presents an access token created in Bytesafe, described below.

The operations table above is the dependable statement of what works. If a command maps to a row in it, the firewall supports it.

How authentication works

Every request to a firewall endpoint carries an access token, including metadata reads. There is no login step and no session.

1. Create a token in the dashboard, or with bsfw. Personal tokens identify a person, Service Access Tokens identify a CI system.
2. Put it in your client's own credential configuration, which is the .npmrc, NuGet.Config, settings.xml, or index URL shown on each ecosystem page.

The client then sends it on every request. That is why an endpoint has nothing to log into and nothing to answer about who a client is: the token is the identity, and it is issued outside the registry protocol. To check which identity a token carries, run bsfw whoami.

Related

• Ecosystems: All ecosystems for per-client setup
• Concept: Execution phases for where policy runs on each operation
• Reference: Selector functions, CLI