Aegis Gateway 2.0

Aegis 2.0 architecture

Aegis 2.0 architecture: composable host integrations, shared governance core, and protected evidence

Aegis governance flow: evaluate, preview, approve, commit, execute

The first image embeds the accessible architecture SVG; the second embeds the validated 2x PNG governance-flow render. Both diagrams are maintained as self-contained SVG sources with validated 2x PNG renders. The governance-flow SVG source is the editable source for the displayed PNG. Re-render them with node tools/render_svg_png.mjs <input.svg> <output.png> 2. The Mermaid blocks below remain separate editable detail views. DocumentationAssetsTest parses the SVGs, checks PNG signatures/dimensions and resolves every documentation link; Mermaid blocks are rendered by mermaid-cli (mmdc) when a local CLI is configured.

1. Shape

One engine, two front doors, three kinds of backend. Every arrow into the engine carries a CallerIdentity that the host established. After durable ALLOW_INTENT, every backend call carries either a static gateway service credential or an exchanged backend-audience token. The verified inbound caller token itself is never forwarded to the backend.

flowchart TB
    subgraph clients["MCP clients (agents, IDEs, desktop apps)"]
        C1["Streamable HTTP client<br/>2025-03-26 .. 2026-07-28"]
        C2["stdio client<br/>(local desktop)"]
    end

    subgraph doorA["Front door A: aegis-gateway + aegis-mcp-security"]
        S1["JDK HttpServer (TLS optional)"]
        S2["JwtVerifier (JWKS / HS256)<br/>or hashed static tokens"]
        S4["OwnServerPerimeter<br/>route groups, exact-origin CORS"]
        S3["StdioHost<br/>(configured identity)"]
    end

    subgraph doorB["Front door B: Apache Knox 3.0 topology"]
        K1["Knox authentication<br/>Shiro, KnoxSSO, JWT federation"]
        K2["identity assertion + AclsAuthz"]
        K3["AegisMcpResource (JAX-RS)<br/>KnoxIdentityBridge"]
    end

    subgraph core["Host-neutral core (zero third-party runtime dependencies)"]
        H["aegis-mcp: McpServerHandler<br/>both protocol eras, header checks,<br/>AdminApi (approvals, catalog, prompts)"]
        E["aegis-engine: GovernanceEngine (tools)<br/>ContentGovernor (resources, prompts, completion)"]
        CAT["ToolCatalog + prompt catalog<br/>CatalogIntegrity pins"]
        SPI["SPI: PolicyDecisionPoint, StateStore, AuditSink,<br/>CredentialProvider, GovernanceHook, DecisionListener"]
    end

    subgraph backends["Backends (unchanged projects)"]
        B1["Existing MCP server<br/>HTTP or stdio"]
        B2["REST API<br/>Flink, Spark UI, Iceberg REST, Kafka Connect"]
        B3["Java client plugin<br/>JDBC, ZooKeeper, Kafka Admin,<br/>Spark Connect (gRPC)"]
    end

    C1 --> S1 --> S2 --> S4 --> H
    C2 --> S3 --> H
    C1 --> K1 --> K2 --> K3 --> H
    H --> E
    E --- CAT
    E --- SPI
    E -->|"McpProxyToolSource / McpContentSource"| B1
    E -->|"HttpToolSource"| B2
    E -->|"ToolSourceFactory (ServiceLoader)"| B3

aegis-config builds the shared graph from one file: hosts call GatewayFactory.build(file, BuildContext) and receive a Gateway (engine, MCP handler, admin API, metrics). Host adapters perform different admission steps, then call the same governance implementation. Equivalent Aegis configuration and normalized identity therefore traverse the same chain; host-level results can differ because Knox and the own host intentionally authenticate and admit routes differently.

Module Role Runtime dependencies
aegis-engine chain, strict JSON, controls, audit, state, trace context, metrics none (JDK 17)
aegis-mcp MCP server handler (both eras), admin API, HTTP and stdio downstream clients engine
aegis-observability-otlp bounded asynchronous OTLP/HTTP span exporter, a DecisionListener engine, mcp
aegis-config strict JSON/YAML config, declarative HTTP tools, OPA, built-in hooks, plugin, hook and state provider loading engine, mcp, observability-otlp; snakeyaml optional
aegis-mcp-guardrails optional project-governance hook engine, config
aegis-mcp-security own-host perimeter: JWT/JWKS and static-token identity, RFC 9728 metadata, route groups, exact-origin CORS engine, mcp, config
aegis-gateway JDK HTTP(S) binding, stdio host, /metrics, shaded runnable jar config, mcp-security, mcp-guardrails, state-derby, snakeyaml
aegis-source-jdbc / aegis-source-zookeeper typed converter sources (type: jdbc, type: zookeeper) config; the engine’s own client
aegis-state-derby optional state.type: derby-local provider config; Apache Derby
aegis-knox3-extension Knox 3.0 Service API (JAX-RS), Subject bridge, lifecycle config; Knox 3.0.0 provided
examples/aegis-examples Kafka Admin plugin, and the tests that load every file in adopters/configurations/ config; kafka-clients optional
examples/aegis-spark-connect Spark Connect plugin (type: spark-connect) config, Spark Connect JVM client
examples/aegis-gateway-spark / aegis-gateway-kafka runnable jars: gateway plus the Spark Connect or Kafka Admin plugin gateway and the plugin

2. Why the core has zero third-party dependencies

The engine must run inside hosts that bring their own libraries. Apache Knox 3.0.0 ships Jackson 2.18.9, snakeyaml 2.4 and Jersey 2.47 (read from its dep/ directory during the cold-install test), and each Apache engine ships its own versions again. A private, strict JSON parser removes every version collision. It also enforces properties that matter to a gateway: duplicate keys are rejected, and depth and size are bounded during the parse. If a proxy and a backend disagree on which of two "name" keys wins, the gateway’s check can be bypassed. YAML support is optional and uses the host’s snakeyaml when present. Heavy clients (Kafka, Spark Connect) live in plugin modules, so a deployment only carries what it configures.

3. Identity and credentials are separate

CallerIdentity carries who the caller is (actor, effective subject, groups, issuer, delegation chain) and deliberately carries no credential.

Backend credentials come from a CredentialProvider, which is called only after pre-execution controls pass and durable ALLOW_INTENT succeeds. Depending on source configuration, the provider returns either a static gateway service credential or an RFC 8693 exchanged, caller-bound backend-audience token. The verified inbound caller token is used only as subject input to the configured token endpoint and is never forwarded to the protected backend.

4. The tool chain and its ordering

sequenceDiagram
    autonumber
    participant C as MCP client
    participant H as McpServerHandler
    participant G as GovernanceEngine
    participant A as AuditSink (hash chain)
    participant P as CredentialProvider
    participant B as Backend

    C->>H: tools/call (+ _meta: traceparent, approvalToken, dryRunReceipt)
    H->>H: era, headers == body (Mcp-Method, Mcp-Name), size and JSON limits
    H->>G: ToolCall + CallerIdentity
    G->>G: 1 exposure, 2 input and scope, 3 policy (PDP)
    G->>G: 5 egress (every URL and DNS answer), 6 rate and budget, 7 breaker
    G->>G: 8 screening + hooks, 4 approval verify, 9 dry-run receipt verify
    G->>G: commit: consume approval and receipt in separate atomic nonce operations
    G->>A: ALLOW_INTENT
    alt audit write fails
        G-->>C: AUDIT_UNAVAILABLE (nothing executed, consumed controls stay consumed)
    end
    G->>P: credentials for this source (only now)
    G->>B: execute (traceparent forwarded, caller token never)
    B-->>G: result
    G->>G: hooks after, redact every string, bound bytes
    G->>A: EXECUTION_RESULT (result digest, redaction count)
    G-->>C: result + _meta decision (requestId, traceId, receipt, approval id)

Design choices:

The dry-run path (validate, run, promote) is the same chain with a preview executor:

stateDiagram-v2
    [*] --> Requested: DESTRUCTIVE call, no token
    Requested --> Previewed: same call with _meta dryRun=true
    Previewed --> Approved: a different approver decides (admin API)
    Previewed --> Denied: approver denies
    Approved --> Executed: token + receipt, same caller, same action binding
    Executed --> [*]
    Approved --> Refused: replay, other arguments, other caller, changed definition, other gateway, expired
    Refused --> [*]
    Denied --> [*]

Preview modes: GATEWAY (the gateway answers, nothing reaches the backend), ARGUMENT (the backend’s own validate-only flag, checked to exist in the schema), TOOL (a separate read tool, for example spark_explain_sql for spark_sql).

5. Catalog integrity (tools and prompts)

Every tool definition (name, title, description, input/output schema, annotations) and every prompt definition (name, description, arguments) is digested.

6. Protocol eras

  2025-03-26 .. 2025-11-25 (legacy) 2026-07-28 (modern)
Selected by initialize params._meta["io.modelcontextprotocol/protocolVersion"]
Session optional Mcp-Session-Id, caller-bound (another principal gets 404) none; Mcp-Session-Id ignored
Headers MCP-Protocol-Version checked against the session; Mcp-Method / Mcp-Name checked when present MCP-Protocol-Version, Mcp-Method, Mcp-Name required and must equal the body (else 400 / -32020)
Discovery initialize result server/discover
List results {tools} {tools, resultType, ttlMs, cacheScope:"private"} (lists are per caller)
Notifications notifications/initialized, notifications/cancelled accepted (202) same

Governance state (approvals, receipts, budgets, pins) never hangs off a session. It is keyed by caller identity and action, so the same controls hold in both eras.

Downstream, HttpMcpClient in AUTO mode probes modern first and falls back to legacy, as the 2026-07-28 backward-compatibility section describes. It re-establishes an expired legacy session once, parses SSE responses, and refuses server-to-client requests on a legacy stream (sampling, elicitation), because they would reach the model outside governance.

Multi Round-Trip Requests (MRTR) work for tools/call, resources/read and prompts/get, the three requests the specification allows:

7. Resources, prompts and completion

They cannot change backend state, but they put data (resources) and instructions (prompts) straight into the model’s context, so each governed read passes the same steps as a READ tool call.

flowchart LR
    R["resources/read uri<br/>prompts/get name<br/>completion/complete ref"] --> X{"1 exposure<br/>route to exactly one source<br/>groups, prompt active"}
    X -->|no| D1["-32010 NOT_EXPOSED / CATALOG_INTEGRITY"]
    X --> I{"2 input + scope<br/>prompt args declared, strings, required"}
    I --> PL{"3 policy<br/>tool = MCP method, class READ<br/>resource mcp:resource:uri / mcp:prompt:name"}
    PL --> EG{"5 egress, 6 rate, 7 breaker,<br/>8 argument screen"}
    EG --> AU["ALLOW_INTENT audit"]
    AU --> EX["execute (credentials now,<br/>traceparent forwarded)"]
    EX --> SH{"result rebuilt from spec fields only,<br/>content URIs inside uriPatterns"}
    SH --> RD{"redact strings, refuse binary<br/>unless allowBinary, bound bytes"}
    RD --> CS{"8 content screen<br/>(what enters the model)"}
    CS -->|match| D2["-32010 PROMPT_INJECTION"]
    CS --> OK["result + EXECUTION_RESULT audit"]

8. Observability

9. State

StateStore holds single-use approval and receipt nonces, pending approvals, rate and budget windows, and, when supported, signed-file serial high-water marks. Each store operation is atomic, but a sequence of operations is not one transaction. TOFU tool and prompt pins are maintained by CatalogIntegrity and optionally persisted to catalog.pinFile; they are not stored by StateStore or shared through PostgreSQL. state.type selects the store (see CONFIGURATION.md):

The postgres provider has a recorded 2026-10-08 run of five provider tests and one two-gateway test against a temporary managed PostgreSQL instance; the engine version was not retained (evidence). Two gateway JVMs sharing one PostgreSQL 17.6 namespace were also run: an approval requested on replica A was decided on replica B, the approved delete ran once, the replay was refused, and one rate window applied across both (evidence). Catalog pins and circuit breakers stay per process, each replica writes its own audit journal, and PostgreSQL replication and failover were not tested (see VALIDATION.md).

10. Deployment shapes

flowchart LR
    subgraph A["Own server (Aegis security)"]
        a1["agent"] -->|"HTTPS + JWT"| a2["aegis-gateway"] --> a3["Spark / Flink / Kafka / MCP server"]
    end
    subgraph B["Inside Apache Knox (Knox security)"]
        b1["agent"] -->|"HTTPS"| b2["Knox topology<br/>authn, identity assertion, ACL"] --> b3["AEGIS_MCP service<br/>(5 jars or 1 bundle in ext/)"] --> b4["Spark / Flink / Kafka / MCP server"]
    end
    subgraph C["Local desktop (stdio)"]
        c1["IDE / desktop app"] -->|"stdio"| c2["aegis-gateway --stdio"] --> c3["local or remote backend"]
    end

11. Trust boundaries

Input Trusted? Handling
Operator config file yes strict parse; unknown keys fatal; secrets only via environment
Caller identity from host yes (host’s job) never anonymous; 401 without it
Request body no strict JSON, bounded, header/body match, schema subset, recursive screening
Upstream tool and prompt definitions no pinned, screened, class can only rise
Backend responses, resources, prompt messages no rebuilt from spec fields, bounded, redacted, content-screened, SSE server requests refused
DNS answers no every answer classified; private classes need an explicit CIDR
traceparent no strictly parsed; only ids are propagated

12. Extending

13. Non-goals

Aegis is a governance and security checkpoint for MCP. It is not an MCP platform. Naming what is deliberately absent is part of the design, because every one of these is a reasonable thing to want and none of them belongs in the same artifact as the enforcement path.

Not in Aegis Why, and what to use instead
Server registry or catalog UI for discovering MCP servers Discovery has its own lifecycle and access model. Aegis governs sources an operator has already configured, pinned and admitted. The optional signed serverCatalog is not a registry: it lists only sources already declared in the configuration and decides at startup whether each may start.
Federation, peer gateways, virtual servers composed from other servers Composition multiplies the ways a tool can be exposed, and every extra path is a path the policy has to cover. One gateway, one configured set of sources
Admin web UI The admin surface is a small JSON API (AdminApi) behind approver groups. A UI is a separate deployable, and it is where CSRF and session bugs live
An observability stack (dashboards, storage, alert rules) Aegis emits hash-chained audit JSONL and Prometheus metrics. Where those go is the operator’s existing stack
WebSocket transport, REST or gRPC proxying of non-MCP APIs Aegis governs MCP over HTTP and stdio. A declarative HTTP source exists to turn an API into governed MCP tools, which is the opposite direction: bring the API into the governed shape rather than widen the front door
LLM token accounting or cost budgeting Aegis budgets calls by tool class. Token spend is a model-gateway concern and needs the model’s own accounting
An A2A front door See ADR-001. Delegation to an agent is governed as a tool call through the a2a source, which is built; serving A2A to other agents is not
Being the model gateway, prompt store or agent framework Aegis sits between an agent and real systems. It has no opinion about which model is used

Two things Aegis deliberately keeps that comparable gateways make optional:

14. Own-host MCP security perimeter

The own-host option provides an Aegis-managed perimeter for deployments that do not use a Knox topology. Where Apache Knox is already the deployment perimeter, Knox supplies its established authentication, identity assertion, and route-admission capabilities before the same shared MCP handler:

TLS server -> identity resolver -> route groups -> body bound -> MCP/Admin handler -> GovernanceEngine

Two related controls apply on every host, not only the own server:

The own-host and Knox integrations both converge on CallerIdentity and the shared MCP governance engine. The Knox service adapter uses public Knox APIs, while the own-host adapter provides the Aegis-managed edge. KnoxPackagingBoundaryTest records the packaging boundary between these integration choices. Runtime source registration, plugin installation, server federation and a registry UI remain outside this perimeter.