Upstreams

Field-level reference for upstream configuration, credentials handling, and cache behavior.

An upstream is one registry a firewall resolves packages from. Upstreams live in the upstreams array of the firewall config. For behavior and patterns, see Upstreams and caching and Configure upstreams.

Shape

{
  "id": "e2de947a",
  "endpoint": "https://npm.acme.internal",
  "credentials": {
    "username": "",
    "password": "",
    "token": "<encrypted>"
  },
  "internal": true,
  "cached": true
}

Fields

Field	Type	Description
`id`	string	Unique within the firewall. Referenced by `publishTarget`, the `upstreamId` selector field, and log entries
`endpoint`	string	Base URL of the registry, in the ecosystem's native protocol
`credentials`	object	`username`, `password`, `token`; all optional. See below
`internal`	boolean	Marks this registry as the authority for its packages. When any internal upstream knows a package name, only internal upstreams' versions are served
`cached`	boolean	Cache responses from this upstream (metadata for a short interval, plus fetched artifacts). Applies to upstreams marked `internal`

Credentials

The auth scheme is inferred from which fields are set; there is no separate auth-type setting.

On fetches, token is sent as Authorization: Bearer. Without a token, username/password are sent as HTTP basic auth. If both are set, the token wins. One compat case: Azure Artifacts endpoints (pkgs.dev.azure.com) receive a token as basic auth in addition to the bearer header.
On publishes forwarded to the publish target, npm follows the fetch behavior above; Maven and NuGet send token as a bearer header (NuGet additionally as X-NuGet-ApiKey) and fall back to username/password as basic auth; PyPI sends a token as __token__ basic auth (the twine convention), or username/password as basic auth.
Encrypted at rest. API responses and exports never contain the plaintext; they carry a placeholder value that preserves an existing stored credential on import.
Config import rejects plaintext credential values. Leave placeholders untouched in exported files. A placeholder for a new firewall or upstream resolves to empty because that target has no stored credential; set it separately after import.

Cache behavior

cached: true requires internal: true. An external upstream with caching enabled is rejected with 400: upstream <id>: caching is only allowed on internal upstreams. The rule holds for the dashboard, the API, and bsfw config import alike.
cached: false disables caching for the upstream, with one override: Maven Central endpoints (https://repo1.maven.org/maven2, https://repo.maven.apache.org/maven2) are always cached. Every other Maven upstream, including a repository manager, follows its own flag.
Maven -SNAPSHOT artifacts are never cached, even from a cached upstream, so a rebuilt snapshot is always fetched fresh.
Cache keys include the firewall config version, so a config change is never answered from cache entries built under the previous version. The change itself propagates across the cluster within a few seconds.
Cache keys include the upstream's credentials, and version listings from an upstream with any credentials set are cached per namespace, for a shorter interval than listings from an upstream without credentials.

Failure behavior

An upstream that cannot be reached, or rejects the firewall's credentials, is skipped during resolution. The remaining upstreams still serve; the failing upstream's packages appear missing rather than producing an install error.

When the upstream is cached and the firewall already holds a copy of what was requested, it can answer from that copy instead of skipping the upstream. That covers a short outage for content already fetched, and nothing else: a DNS failure and an upstream 404 are not covered.

Concept: Upstreams and caching
How-to: Configure upstreams, Prevent dependency confusion
Reference: Firewall config