Ferrum Foundry v0.5.4

Ferrum Foundry v0.5.4

Foundry v0.5.4 is a security and fix patch release. It pairs with the same
published Ferrum Edge v0.9.14 and canonical contracts-edge-0.9.14 as
v0.5.3. Hosted qualification evidence is recorded in the
compatibility record;
the published image digest is listed under Docker below.

This release bounds what a namespace-scoped session can reach through the BFF
and ships the source merged since v0.5.3. The Edge pin, platform digests,
contract pin, plugin sensitivity table and guided schema hashes are unchanged
from v0.5.3. It changes no runtime profile or authority tier, but it narrows
what a session with namespace grants may do; read Upgrading
before deploying it.

Qualified pairing

Foundry	v0.5.4; previous release v0.5.3; image digest and source commit under Docker below
Ferrum Edge	Ferrum Edge v0.9.14, ferrumedge/ferrum-edge@sha256:15442f1b1d1758023fe871fe57be50f19caf34bbe6c499a6812f4ffd0da5e3f8, commit 9bd4d5f9caa4ebe8f0ea13e76d8a6e2172eaca7d, unchanged from v0.5.3
Edge platform manifests	linux/amd64 sha256:12a8cd56090c0d4511bb3015b240e606b1b87989c644157566b8f6b6f635b3c2; linux/arm64 sha256:19d2886ed8c192cb0daba48ef0a27a0cd0526449dac74bf9438502322aabd9f2
Upstream distribution evidence	Edge release run 37585311307, all 20 jobs successful; published release 405571232 at 2026-10-07 08:59:56 UTC
Canonical contracts	contracts-edge-0.9.14, commit ddbdd845733b7046c4393ac951011dafb774db33, release 406650065, unchanged from v0.5.3
Foundry qualification	Hosted run, attempt, source and tested merge recorded in the qualification object of docs/compatibility.json. v0.5.3's qualification of the same pin does not qualify this release
Qualified support	Existing SQLite database mode, writable and read-only, trusted-proxy starter, viewer/operator/admin, Chromium, Node 22/24 gates and amd64/arm64 Container Gates

The unchanged Edge contracts retain ferrum-edge#5661 resource ETag/If-Match
handling and ferrum-edge#5726 proxy-scoped plugin configuration filtering.
Binary hashes, OpenAPI identity and registry verification limits are recorded
in
compatibility.

Changes since v0.5.3

• Namespace route ceiling (#562). A session with namespace grants may now
  reach only the gateway admin routes its namespace grant actually scopes,
  plus a small fleet-wide allowlist. Every other route, including any route
  Foundry has not classified, is refused by the BFF with
  403 Namespace access denied before a JWT is signed or the gateway is
  contacted. HEAD is classified like GET. The credential-read denials and the
  unsafe-path 400 run first and keep their documented codes.
• Health summary for scoped sessions. /health and /status answer a
  namespace-scoped session with only status, timestamp, mode,
  admin_writes_enabled and ready, the facts the capability model reads.
  Upstream length, validator and range headers are dropped.
• Fleet TLS is read and validate only for scoped sessions. They may read
  fleet TLS material and call the stateless validate route, but may no longer
  create, replace, rotate, renew, finalize or delete it.
• Navigation follows the ceiling. For a namespace-scoped session the
  sidebar hides Dashboard, Metrics, Cluster and Mesh, which the BFF now
  refuses. The Audit Log stays and lists the rows of the session's own
  namespaces.
• Publication record (#561). The verified v0.5.3 publication evidence is
  recorded, and the immutable v0.5.3 record is preserved byte for byte.
• Version. Package and lockfile root versions are 0.5.4.

Upgrading

Breaking for namespace-scoped principals. A principal with namespace
grants is a trusted-proxy identity whose namespaces header names one or more
namespaces, or a static-mode session whose FERRUM_JWT_NAMESPACES lists exact
names. From v0.5.4 such a session:

• gets only the health summary above from /health and /status, never the
  detailed view;
• can read and validate fleet TLS material but cannot create, replace, rotate,
  renew, finalize or delete it;
• may use only known namespace-scoped admin routes, each naming one of its
  grants in X-Ferrum-Namespace, plus the documented fleet-wide allowlist;
• cannot use fleet-global routes such as /cluster, /overload or mesh
  egress scope (/mesh/egress-scope), which are denied with 403.

Unrestricted principals are unchanged: a trusted-proxy admin asserted
without a namespaces header, or static mode with FERRUM_JWT_NAMESPACES='*'.
If an operator needs the Cluster, Mesh or Metrics surfaces, or fleet TLS
writes, give that identity an unrestricted admin mapping. The starter maps
every group, ferrum-admins included, to a namespace, so every starter user
is scoped. See
Namespace route ceiling
in docs/authentication.md for the full route classes.

Edge records fleet-wide actions under its default ferrum namespace, so a
session granted ferrum reads those audit rows. Grant ferrum only to
identities that may see fleet-wide audit.

Security

This release hardens namespace-scoped authorization in the BFF. Deployments
that rely on namespace grants to separate tenants or teams should upgrade.
The fix is enforced in the BFF; Ferrum Edge remains an enforcement point and
no Edge upgrade is required.

Known limits

The ceiling is enforced by Foundry's BFF only. Clients that reach the Ferrum
Edge admin API directly are governed by Edge's own authorization. A new Edge
admin route is refused to scoped sessions until Foundry classifies it. #547
account-level immutability decisions remain pending.

No unrelated upstream approval is implied. Existing best-effort/unqualified modes, eBPF variants, real-gateway scale limits and
browser limits remain unchanged.

Publication and deployment

Deploy Foundry v0.5.4 against the paired Ferrum Edge v0.9.14 image,
ferrumedge/ferrum-edge@sha256:15442f1b1d1758023fe871fe57be50f19caf34bbe6c499a6812f4ffd0da5e3f8.
In production, pin the released Foundry multi-architecture index digest listed
under Docker below rather than a mutable tag. Versioned v0.5.3, v0.5.2,
v0.5.1, v0.5.0 and v0.4.0 notes and records remain byte-for-byte unchanged.
Their source, image and CI evidence are historical; published version tags
must never move.

Docker

docker pull ferrumedge/ferrum-foundry:v0.5.4
docker pull ghcr.io/ferrum-edge/ferrum-foundry:v0.5.4

Both tags name the multi-architecture index sha256:645061444dc4d824aa256796e3891618e9f8446e7b3eb95c184a3147209975e1, built from
commit 0a855ddeef1e4a998a60a2e0c61e71510365b70e. Release version tags are never reassigned; pin
the digest for byte-identical deployments:

docker pull ferrumedge/ferrum-foundry@sha256:645061444dc4d824aa256796e3891618e9f8446e7b3eb95c184a3147209975e1

Production quick start

Run Foundry only behind an identity-aware reverse proxy that removes
client-supplied identity headers and injects the trusted proxy proof:

export FERRUM_JWT_SECRET=$(openssl rand -hex 32)
export FERRUM_TRUSTED_PROXY_SECRET=$(openssl rand -hex 32)

docker run \
  -e FERRUM_ADMIN_URL=https://your-gateway:9443 \
  -e FERRUM_JWT_SECRET \
  -e FERRUM_AUTH_MODE=trusted-proxy \
  -e FERRUM_TRUSTED_PROXY_SECRET \
  -p 127.0.0.1:8080:8080 \
  ferrumedge/ferrum-foundry:v0.5.4

Configure the proxy to send X-Ferrum-Auth-Secret,
X-Forwarded-User, X-Ferrum-Role, and exact
X-Ferrum-Namespaces grants. See
Production authentication.