Aegis Gateway 2.0

ADR-002: Knox 3.0.0 is the current proof point; Knox 3.1 (Jakarta) is the target

Context

aegis-knox3-extension is a thin Knox service that reads the Subject established by Knox’s provider chain and hands MCP requests to the shared Aegis governance plane. It compiles against the released Knox 3.0.0 public API in provided scope, which uses javax.servlet 4.0.1 and javax.ws.rs 2.0.

At the Knox trunk snapshot inspected on 2026-10-03, 3.1.0-SNAPSHOT had moved to the Jakarta namespace: its root pom.xml set jakarta.servlet-api 6.0.0, jakarta.ws.rs-api 3.1.0, and Jersey 3.1.12. That snapshot also carried KnoxIDF identity work, including RFC 8693 token-exchange constants in gateway-util-common (KnoxIDFConstants) and the JWT federation provider (JWTFederationFilter). These are historical upstream observations from the 2026-10-03 design snapshot, not claims about current Knox trunk.

A javax-built extension does not load in a Jakarta container. Aligning Aegis delegated identity with KnoxIDF and running on Knox 3.0.0 javax are therefore two different Knox lines.

Evidence at the decision date

Decision

  1. Keep aegis-knox3-extension on Knox 3.0.0 javax as the released-Knox proof point. Claim only what candidate-bound evidence shows.
  2. Target the Knox 3.1 Jakarta API for the next host extension, as a separate module, once Knox 3.1.0 is released and its artifacts are published. Building against an unreleased snapshot is not a reproducible release input.
  3. For the proposed Knox 3.1 path, map the delegated identity, actor chain, and any token established or exchanged by KnoxIDF into Aegis, with the mapping reviewed by Knox maintainers. This does not describe all Aegis hosts: the current own host supports configured RFC 8693 token exchange. The Knox 3.0 path does not bind a verified inbound subject token for that Aegis provider, so the provider fails closed there.
  4. Keep the governance plane identical across both host modules. The host module stays thin: identity mapping, body bounding, and delegation to the shared Gateway.

Consequences