Ferrum Foundry v0.5.5

Ferrum Foundry v0.5.5

Foundry v0.5.5 pairs with published Ferrum Edge v0.9.15, a security release,
and canonical contracts-edge-0.9.15. Hosted qualification evidence is
recorded in the
compatibility record;
the published image digest is listed under Docker below.

This release moves the development and CI pin to published Ferrum Edge
v0.9.15, adopts the existing canonical contract scope at
contracts-edge-0.9.15, and aligns Foundry's plugin templates, guided
rate-limiting editor and backend TLS forms with the Edge v0.9.15 admin
contract. It changes no runtime profile or authority tier. Edge v0.9.15 fixes
26 published Ferrum Edge security advisories; read Upgrading
before deploying.

Qualified pairing

Foundry	v0.5.5; previous release v0.5.4; image digest and source commit under Docker below
Ferrum Edge	Ferrum Edge v0.9.15, ferrumedge/ferrum-edge@sha256:29b468dfeea13b1ecaac8dfbc7e019f310e71e647611d43800a1dc64436eaca3, commit 25b37395ff61bfea0f3ffd189d9011c4984fa755
Edge platform manifests	linux/amd64 sha256:0404dc6d70d67abb70feea4e5aa295fdb1c19a0968900f467fc4b908528d19d1; linux/arm64 sha256:51b8134770441b3ad340ba87ca9acd8a03fd864315c54d79911b27d95437c91a
Upstream distribution evidence	Edge release run 37823250818, all 20 jobs successful; published release 407222520 at 2026-10-08 20:11:03 UTC
Canonical contracts	contracts-edge-0.9.15, commit 6fb64c5dc2e014204c17609fc717d976f3b4589e, release 407246047 at 2026-10-08 20:42:07 UTC
Foundry qualification	Hosted run, attempt, source and tested merge recorded in the qualification object of docs/compatibility.json. v0.5.4's qualification of the previous Edge 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.
The default Docker Hub image's ferrum-edge and ferrum-cni binaries match
the published release assets on both architectures. Binary hashes, OpenAPI
identity and registry verification limits are recorded in
compatibility.
Anonymous GHCR access and an Edge OCI revision label are not claimed.

Changes since v0.5.4

• Plugin templates use FERRUM_PLUGIN_SECRET_<NAME> references. Edge
  v0.9.15 refuses, with 400, any plugin-config environment reference outside
  the FERRUM_PLUGIN_SECRET_<NAME> namespace (ferrum-edge#6089). The
  ai_semantic_firewall (provider.api_key_env), ai_stream_router
  (providers[].api_key), api_chargeback_sink (clickhouse.password_ref)
  and proxy_alerts (webhook_url_env) templates now name
  FERRUM_PLUGIN_SECRET_OPENAI_API_KEY,
  FERRUM_PLUGIN_SECRET_ANTHROPIC_API_KEY,
  FERRUM_PLUGIN_SECRET_CLICKHOUSE_PASSWORD and
  FERRUM_PLUGIN_SECRET_ALERTS_SLACK_WEBHOOK. The plugin-defaults contract
  expects Edge's new unset-variable refusal for ai_stream_router and the
  renamed variable in the proxy_alerts refusal; 74 templates are still
  admitted as shipped.
• Guided rate limiting models ipv6_prefix. Edge v0.9.15 groups IPv6
  rate-limit keys by prefix (ferrum-edge#6079). The guided editor adds an IPv6
  prefix length field (1–128; omitted means 64, and 128 restores
  per-address keys). It is written only when set, so existing configurations
  are unchanged. The RateLimitingConfig schema digest and
  PLUGIN_SCHEMA_SPEC.ref move to the v0.9.15 source; the other four guided
  components are byte-identical.
• Backend TLS reference scope. The proxy and upstream Backend TLS sections
  state that, where the gateway enforces namespace claims, an operator can set
  the client certificate, client key and server CA only to inline PEM,
  system:// or a k8s:// Secret in the namespace (ferrum-edge#6094). Edge's
  400 for any other reference is shown as returned; stored values are kept.
• LDAP consumer_mapping and X-Authenticated-Identity. Edge v0.9.15
  removes the LDAP consumer_mapping option and reserves the gateway-owned
  X-Authenticated-Identity header (ferrum-edge#6088). No Foundry template or
  form sets either; a unit test keeps consumer_mapping out of the ldap_auth
  template, and Edge's refusal of a raw config that sets either is shown as
  returned.
• Pins and contracts. Starter, development command and current record use
  the same published Edge digest. Package and lockfile root versions are 0.5.5.
  The same 18 contract files are taken byte-exact from canonical commit
  6fb64c5dc2e014204c17609fc717d976f3b4589e after main Validate contracts run
  37841329610 succeeded. Only the vocabularies' Edge provenance, OpenAPI
  digest and a new catalog note on the v0.9.15 config-schema changes, and the
  complete canonical invalid expectations, change; the latter adds a
  diagnostic-ref and a gateway-headers negative without Foundry adopting those
  schemas. All 82 plugin entries, provisioning values, manifest schema and all
  12 fixtures are unchanged. Shared status remains EXISTING/implemented at
  Alloy owner 81cbb; Alloy stays unpublished.
• Plugin sensitivity. Edge's registered plugin set and PluginConfigBase
  are unchanged, and its projection source is byte-identical to v0.9.14, so the
  sensitivity table is unchanged and its provenance names the v0.9.15 source.
  Schema provenance
  records the guided schema review.
• Publication record (#564, #566). The verified v0.5.4 publication evidence
  and its published advisory reference are recorded, and the immutable v0.5.4
  record is preserved byte for byte.

Upgrading

Upgrade Ferrum Edge. Edge v0.9.15 is a security release that fixes 26
published Ferrum Edge advisories (5 high, 19 medium, 2 low), covering
namespace isolation, mesh and Gateway API authorization, plugin-config
secrets, identity headers, HTTP/3 and per-client resource limits. Operators
should upgrade Edge to v0.9.15 and deploy Foundry v0.5.5 with it. Before
upgrading Edge, read its
Upgrading to 0.9.15
guide; several changes are breaking. Those that affect what you configure
through Foundry:

• Plugin-config environment references. Rename every variable a plugin
  config references (and its _FILE / _VAULT / _AWS / _AZURE / _GCP
  source) into FERRUM_PLUGIN_SECRET_<NAME> in the gateway environment, then
  update the plugin configs. Configurations created from earlier Foundry
  templates name OPENAI_API_KEY, ANTHROPIC_API_KEY,
  FERRUM_CLICKHOUSE_PASSWORD or FERRUM_ALERTS_SLACK_WEBHOOK. Edge refuses
  to save them unchanged; stored rows that still reference them are
  quarantined, or omitted with a warning for optional plugins such as
  proxy_alerts. The serverless_function Azure and GCP fallbacks now read
  FERRUM_PLUGIN_SECRET_AZURE_FUNCTIONS_KEY and
  FERRUM_PLUGIN_SECRET_GCP_CLOUD_FUNCTIONS_BEARER_TOKEN.
• External identities. Backends that read X-Consumer-Username for JWKS,
  OIDC, introspection, LDAP or SOAP identities must read
  X-Authenticated-Identity instead. Remove LDAP consumer_mapping and any
  header rule that sets X-Authenticated-Identity.
• Operator backend TLS references. Where the gateway enforces namespace
  claims, automation that writes backend TLS file paths or secret-manager
  references with an operator identity must use an admin identity.
• IPv6 quotas and MCP sessions. IPv6 clients in one /64 now share a
  rate-limit budget unless ipv6_prefix says otherwise, and aggregate MCP
  sessions are capped per principal (sessions.max_sessions_per_principal,
  default 128). body_validator refuses
  grpc_max_decompressed_size_bytes: 0.
• gRPC and WebSocket routes. Native gRPC and WebSocket requests on a route
  whose authentication or admission plugins cannot run on that flavor are now
  refused: WebSocket with 403, native gRPC with PERMISSION_DENIED.

Foundry itself adds no breaking change over v0.5.4.

Known limits

Foundry does not refuse a backend TLS reference or a plugin header destination
locally; Edge's admission is authoritative and its refusal is shown as
returned. mcp_gateway session caps and body_validator limits are edited as
raw JSON. #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.5 against the paired Ferrum Edge v0.9.15 image,
ferrumedge/ferrum-edge@sha256:29b468dfeea13b1ecaac8dfbc7e019f310e71e647611d43800a1dc64436eaca3.
In production, pin the released Foundry multi-architecture index digest listed
under Docker below rather than a mutable tag. Edge v0.9.15 keeps ConfigSync
protocol revision 3, so its control and data planes must run the same build.
Versioned v0.5.4, 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.5
docker pull ghcr.io/ferrum-edge/ferrum-foundry:v0.5.5

Both tags name the multi-architecture index sha256:5bdfa947adead6895e9dbdc4b4db5ed7e960bd7fc5ebb9872ac722ced86a8b0f, built from
commit 359e1cd4efab110475b294452dfeeaefc7a4d5e6. Release version tags are never reassigned; pin
the digest for byte-identical deployments:

docker pull ferrumedge/ferrum-foundry@sha256:5bdfa947adead6895e9dbdc4b4db5ed7e960bd7fc5ebb9872ac722ced86a8b0f

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.5

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