<!--
  Copyright 2026 Viquar Khan and the Aegis MCP Gateway contributors

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
# Claims matrix

This is the release-evidence index for Aegis 2.0. A product claim needs an implementation anchor, an
assertion anchor and a result classification. It is deliberately stricter than “a test exists.” A
contract route harness can prove configuration rendering and governance flow; it cannot certify a third-party
product release. A converter tested against an embedded Apache engine can prove converter behavior; it
cannot certify every database or client implementation.

## Status vocabulary

| Status | Meaning |
| --- | --- |
| **verified-current** | The named command has a retained immutable artifact bound to the reviewed candidate commit/tree and target. |
| **verified-historical** | A preserved earlier run exists, but the current working tree has not repeated it. |
| **recorded** | The run is documented in this repository. The release-candidate repeat is on the [roadmap](../ROADMAP.md#next-release-candidate-evidence). |
| **implemented-contract** | Code and governance flow are tested against a contract or protocol harness, not a target product. |
| **implemented-pending** | The source/configuration exists but no adequate target execution has happened. |
| **not shipped** | The capability is intentionally absent or remains on the roadmap. |

## Core control plane

| ID | Claim | Implementation and assertion | Evidence target | Status | Revalidate when |
| --- | --- | --- | --- | --- | --- |
| C01 | Every governed call follows the fixed control order and fails closed when a required control cannot run. | `GovernanceEngine`; `GovernanceEngineTest` and `ControlsTest` | deterministic engine tests | recorded | chain, deny-code or SPI change |
| C02 | Approval and destructive-run receipts bind to the caller, the full action binding (gateway, tool, class, source, resources, argument digest, pinned definition digest) and one-time state; the requester (under any NFKC or case spelling) and delegated callers cannot approve; approval decisions are journaled before a token is issued. Promotion is at-most-once: consumed approval or receipt nonces remain consumed when later intent journaling fails, and no backend call occurs. | `ApprovalService`, `VrpService`, `Action.binding`; `GovernanceEngineTest`, `SeparationOfDutiesTest` | deterministic engine tests | recorded | approval, receipt, binding or state-store change |
| C03 | A `TOOL` preview uses the actual READ preview tool, not the destructive tool being validated. | `GatewayFactory.SourceBuild`; `DryRunPreviewToolTest` | converter-shaped test source | recorded | source binding or dry-run parser change |
| C04 | Input and output controls inspect nested data, with bounded parsing and redaction. | `SchemaValidator`, `ValueWalker`, `OutputGuard`; engine tests | deterministic engine tests | recorded | JSON, screen or output-control change |
| C05 | Egress checks inspect declared and embedded HTTP(S) targets, classify DNS answers, and bound outbound reads. | `EgressGuard`, `BoundedHttp`; `ControlsTest` | deterministic engine tests | recorded | egress or HTTP-client change |
| C06 | Audit intent is written before backend execution and records form a locally verifiable hash chain. If intent journaling fails after at-most-once control consumption, no credential lookup or backend execution occurs. | `HashChainFileAuditSink`; audit and engine tests | local file system | recorded | audit format or store change |
| C07 | Resources, prompts and completion traverse governance as read operations when enabled. | `ContentGovernor`; content tests | deterministic engine tests | recorded | MCP/content operation change |
| C08 | OTLP span export is bounded, asynchronous, carries no identity, arguments or results, and cannot slow or change a governed call. | `OtlpSpanExporter`; `OtlpSpanExporterTest` | local collector test endpoint that asserts the OTLP/JSON document shape | implemented-contract | exporter or span attribute change |
| C09 | A valid JWT without a route's required OAuth scope is refused with 403 `insufficient_scope`, and published OAuth URLs are https or loopback only. | `OwnServerPerimeter`, `JwtVerifier.verifyWithScopes`, `ProtectedResourceMetadata`; `ScopeEnforcementTest`, `ProtectedResourceMetadataTest` (both modules) | deterministic tests and the JDK HTTP server | recorded | perimeter, identity or OAuth metadata change |
| C10 | Per-tool `actionScopes` require exact, case-sensitive verified OAuth scopes at step 2, before resource scopes, policy, approval, credentials or the backend; missing scopes deny `SCOPE_DENIED` naming them; the requirement is part of the approval and receipt binding; identities without OAuth grants (static, SPIFFE, stdio, Knox) are denied scoped tools. | `GovernanceEngine`, `Action.binding`, `CallerIdentity.scopes`, `JwtVerifier`, `GatewayFactory`; `GovernanceEngineTest.missingActionScopeDeniesBeforeCredentialsOrBackendAndFullGrantProceeds`, `GatewayFactoryTest.actionScopesAreTrustedToolRequirementsAndDenyBeforeBackendAccess`, `SeparationOfDutiesTest.tokensFromAnotherGatewaySharingTheKeyAreRejected`, `JwtVerifierTest`, `ScopeEnforcementTest` | deterministic tests | recorded | scope parsing, identity, binding or control-order change |

## Source and adapter evidence

| ID | Claim | Implementation and assertion | Evidence target | Status | Revalidate when |
| --- | --- | --- | --- | --- | --- |
| S01 | The shipped inventory includes seven named shared reference profiles, one separate teaching template, and 27 deployable adapter configurations with 123 tools. | shared and adapter YAML configs; `AdapterConfigsTest`; `DocumentationClaimsTest` | parsed configurations and layout contracts | recorded | any shared profile, adapter config or tool change |
| S02 | The shipped comparison surface has 165 tools: 152 successors of the 0.1 inventory, ten Apache Burr (incubating) tools, two Kafka Admin reads, and one Superset chart read. No shipped tool is less guarded. Arrow, Beam, Hudi, Kudu, and Ozone are on the [roadmap](../ROADMAP.md#later-sources-and-engine-operations). | `Coverage01VsTwoTest` | frozen 0.1 inventory and 2.0 YAML | recorded | any config or 0.1 inventory change |
| S03 | JDBC metadata/query behavior and result bounds work against actual Apache software. | `aegis-source-jdbc`; `JdbcToolSourceTest` | Apache Derby 10.16.1.1 | recorded | JDBC source change |
| S04 | ZooKeeper data-tree operations, optimistic versions, binary handling and path rules work against actual Apache software. | `aegis-source-zookeeper`; `ZooKeeperToolSourceTest` | ZooKeeper 3.9.3 through Curator TestingServer | recorded | ZooKeeper source change |
| S05 | Configured ZooKeeper AdminServer command names exist in ZooKeeper's own command registry. | `ZooKeeperAdminCommandsTest` | ZooKeeper `Commands` registry | recorded | ZooKeeper admin config change |
| S06 | A working-tree run was reported for Flink source governance against a real local Flink 1.20.1 MiniCluster; no candidate-bound artifact is retained. | `RealFlinkTest` | Flink 1.20.1 MiniCluster | recorded | Flink source, Flink version or config change |
| S07 | Working-tree runs were reported for Spark read-source governance and Spark Connect source governance against local Spark 4.0.1 runtimes; Spark standalone submission/kill was not exercised. | `RealSparkTest`, `RealSparkConnectServerTest` | Spark 4.0.1 driver UI; Spark Connect 4.0.1 local server | recorded | Spark, Spark Connect or source/config change |

| S08 | Iceberg catalog governance worked against an official REST catalog server in retained historical two-door runs. | `IcebergFrontDoorsTest` (own host at `2026-10-04T23:40:55Z`, Knox at `2026-10-04T23:41:50Z`), `RealIcebergRestCatalogTest` | Iceberg 1.10.1 RESTCatalogServer | verified-historical | any later source/config change |
| S09 | Kafka Admin and Connect governance worked against a broker and worker in retained historical two-door runs. | `KafkaFrontDoorsTest` (own host at `2026-10-05T01:28:15Z`, Knox at `2026-10-05T01:29:32Z`), `ExampleConfigsTest.kafkaConnectAndAdminClient` | Kafka 3.9.1 KRaft and Connect | verified-historical | any later source/config change |
| S10 | HTTP adapter configs are parsed, routed and governed, and target-version compatibility needs a retained real-engine run for each target. | `AdapterConfigsTest` | contract route harness | implemented-contract | target engine real run |
| S11 | Arrow, Beam, Hudi, Kudu, and Ozone are planned typed sources and are not part of this release. | absence from the `adopters/configurations/adapters/<adopter>/` profile directories; `Coverage01VsTwoTest.UNIMPLEMENTED_ENGINES` | source inspection and executable verdict accounting | not shipped | a real source for any of the five |

## Hosts and integrations

| ID | Claim | Implementation and assertion | Evidence target | Status | Revalidate when |
| --- | --- | --- | --- | --- | --- |
| H01 | The own-server host authenticates JWTs and governs a real local HTTP request. | `GatewayHostTest` | local JDK HTTP server and local JWKS fixture | recorded | host or identity change |
| H02 | The Knox extension maps a Knox Subject and governs a proxied MCP call. | `KnoxExtensionTest` | Knox 3.0.0 API plus handler-independent test MCP server | recorded | Knox extension or Knox version change |
| H03 | A Knox 3.0.0 cold-install transcript is retained for the stock gateway, demo LDAP, and `AclsAuthz`. | `docs/evidence/knox-3.0.0-cold-install/` | stock Knox 3.0.0 and a test MCP backend | recorded | before any release or Knox claim broadening |
| H09 | A preserved source comparison found no packaged Knox classes at its 2026-09-29 revisions; the current packaging boundary remains a separate executable assertion. | `KnoxPackagingBoundaryTest`; `tools/provenance/compare_knox_source.py` | historical `knox-source-comparison.json`; current POMs, production source, and built jars | verified-historical | host packaging, extension import or Knox baseline change |
| H04 | Iceberg REST integration used the published Iceberg REST Catalog protocol, not a private endpoint model, in the retained 2026-10-04 UTC run. | `iceberg.yaml`, `IcebergFrontDoorsTest`, `RealIcebergRestCatalogTest` | Apache Iceberg REST Catalog API | verified-historical | Iceberg config or catalog version change |

## Rules for changing this file

1. Add or update a row whenever an externally visible capability, count or compatibility claim changes.
2. Change **verified-current** to **verified-historical** after any relevant code/configuration change until
   the exact target run repeats.
3. Preserve the command output or raw transcript under `docs/evidence/` before promoting a row to
   **verified-current**. The evidence must bind the exact candidate commit and tree, include a SHA-256
   manifest, and retain or content-address the selected Surefire/reactor output.
4. A test double must be identified, never implied away. A source route, a deterministic response and a real
   product response are different evidence classes.
5. Update each referenced documentation sentence in the same change. `DocumentationClaimsTest` guards
   the inventory arithmetic; this matrix is the review surface for the remaining qualitative claims.

## MCP security additions

| ID | Claim | Implementation and assertion | Evidence target | Status | Revalidate when |
| --- | --- | --- | --- | --- | --- |
| H05 | Own-server route groups reject an identity before its MCP/admin body is buffered or dispatched. | `OwnServerSecuritySettings` (`host.routes`), `OwnServerPerimeter`, `AegisServer.serve`; `OwnServerPerimeterTest.routeAdmissionUsesIdentityAndRouteGroupBeforeAnyBodyIsNeeded`, `GatewayHostTest.ownHostRouteGroupsAndCorsRunBeforeMcpDispatch` | local JDK HTTP server | recorded | perimeter or host binding change |
| H06 | Browser preflight uses exact origins and cannot advertise an origin the common MCP handler rejects. | `OwnServerSecuritySettings` (`host.cors`), `OwnServerPerimeter.preflight`, `AegisServer.preflight`; `OwnServerPerimeterTest.corsPolicyUsesExactOriginsAndHeaderNormalization`, `GatewayHostTest.corsPreflightCannotAdvertiseAnOriginTheMcpHandlerRejects` | local JDK HTTP server | recorded | CORS or origin-check change |
| H07 | Own-server OAuth protected-resource metadata follows RFC 9728 and is bound to the JWT audience unless explicitly escaped. | `ProtectedResourceMetadata`, `OwnServerSecuritySettings` (`host.oauth`); `ProtectedResourceMetadataTest` (both modules), `OwnServerSecuritySettingsTest.oauthMetadataRequiresAudienceBindingUnlessExplicitlyEscaped` | local JDK HTTP server | recorded | OAuth metadata or identity change |
| H10 | In the retained 2026-10-05 run, the dated `knox-bundle` jar loaded in a stock Apache Knox 3.0.0 gateway process and governed MCP calls end to end: Knox demo-LDAP authentication and `AclsAuthz` admitted the route, Aegis denied a reader's destructive call, required an independent approval and a dry-run receipt, executed the approved delete on a real ZooKeeper 3.9.3 server, and refused the replay; both audit journals verified. | `ZooKeeperFrontDoorsTest` (OWN_HOST and KNOX); [retained run](https://github.com/vaquarkhan/aegis-mcp-gateway/blob/{{ site.github.source.branch }}/examples/adopters/zookeeper/results/knox-transcript.log), knox-bundle SHA-256 `0726C4CE71D23856F8FE9A58BE2C80E7FC7E4AE740ED70E8ECC8CBFB2617B780` | stock Knox 3.0.0 (`bin/gateway.jar`) with the bundle in `ext/`, real ZooKeeper 3.9.3, 2026-10-05 | verified-historical | any extension, bundle, Knox version or candidate change |
| H08 | The Knox bundle contains the Aegis engine, MCP, OTLP, configuration and PostgreSQL state modules, the PostgreSQL driver and the extension, and no Knox, servlet, JAX-RS, Jersey, Jackson or SnakeYAML class. | `aegis-knox3-extension/pom.xml` shade include list; `KnoxPackagingBoundaryTest.builtHostsShareAegisGovernanceButNotHostImplementations` reads the built `knox-bundle` jar | built jar in the default reactor | recorded | shade list or dependency change |
| S12 | `derby-local` persists durable local governance state for one process, with exact nonce and rate semantics. | `aegis-state-derby`, `StateStoreFactory`; `DerbyStateStoreTest`, `GatewayHostTest.derbyLocalStateProviderIsDiscoveredByTheOwnServer` | Apache Derby 10.16.1.1 embedded | recorded | state store or Derby version change |
| S13 | A quarantined MCP/HTTP/plugin source contributes no callable tool and must identify its evidence reference. | `sources[].trust`, `GatewayFactory.SourceBuild.bind`; `GatewayFactoryTest.sourceTrustQuarantineHidesEveryToolUntilOperatorConfigActivatesTheSource` | deterministic configuration test | recorded | source binding change |
| S14 | In the historical 2026-10-08 managed PostgreSQL run, two PostgreSQL providers reportedly shared nonce/rate state, and persistence, expiration, escaped scans, invalid rate requests, environment-named credentials, and signed serial high-water rollback protection behaved as described. The engine version was not retained, and the run is not candidate or active-active certification. | `PostgresStateStoreIT`; [PostgreSQL validation evidence](POSTGRES-RDS-VALIDATION.md) | temporary managed PostgreSQL instance, deleted after the run; no immutable raw artifact retained | recorded | state provider, PostgreSQL version, candidate release, or deployment topology change |
| S15 | In the historical 2026-10-03 run, two gateway processes using one `postgres` namespace reportedly shared approvals, single-use approval and receipt nonces, signed serial high-water state, and rate windows. The run did not cover replication, failover, or a release candidate. | `TwoGatewayProcessesPostgresIT`; [two-gateway evidence](POSTGRES-TWO-GATEWAYS.md) | two `Main` JVMs, real PostgreSQL 17.6 on loopback; no immutable raw artifact retained | recorded | state provider, approval or rate code, PostgreSQL version, or candidate release change |
| S16 | With `audit.checkpoint` the journal exports its head on a record count, a timer, open and close; it refuses to reopen a journal that is shorter than or different at the last exported head without exporting anything, and `--verify-audit --checkpoints` reports truncation and regeneration that the chain alone accepts. | `HashChainFileAuditSink`, `AuditCheckpointVerifier`, `Main`; `AuditCheckpointTest`, `MainAndSettingsTest.auditCheckpointsAreWrittenFromConfigAndCheckedFromTheCommandLine`, `AuditCheckpointAndManifestConfigTest` | deterministic file tests | recorded | audit sink, checkpoint format or CLI change |
| S17 | A signed `catalog.manifest` (Ed25519, verified before parsing) activates exactly its pinned tools in `REQUIRE_PINS`; a changed definition is quarantined, an edited manifest, another key or another gateway name stops start-up, and a conflicting inline pin is refused. The gateway jar generates keys, creates a manifest from a reviewed `GET /aegis/v1/catalog` reply, signs and verifies. | `SignedCatalogManifest`, `GatewayFactory`, `CatalogManifestCommands`; `SignedCatalogManifestTest`, `SignedCatalogManifestFlowTest` (real own host), `AuditCheckpointAndManifestConfigTest` | JDK Ed25519; real own host on loopback | recorded | manifest format, signature algorithm or pin semantics change |
| S18 | Historical 2026-10-03 OpenBao and 2026-10-05 Vault runs reportedly showed strict secret replacement and fail-closed KV v2 behavior. Neither run retained immutable raw output; Vault namespaces and server TLS were not exercised. | `FileSecretProvider`, `VaultKvSecretProvider`, `SecretProviderFactory`; `SecretProvidersTest`, `VaultKvSecretProviderIT`; [OpenBao evidence](SECRETS-OPENBAO.md) | real OpenBao 2.7.1 and Vault 1.17.6 dev servers on loopback | recorded | provider code, KV API or OpenBao/Vault version change |
| H12 | File-based SPIFFE identity tests exercise real JDK TLS with `keytool`-issued certificates: mapped URI SANs authenticate, while missing, untrusted, ambiguous, wrong-domain, and unmapped certificates fail. They do not exercise SPIRE Workload API issuance. | `SpiffeIdentity`, `OwnServerSecuritySettings`, `AegisServer`; `SpiffeMutualTlsTest` (real TLS), `SpiffeIdentityTest` | JDK TLS with `keytool`-issued certificates, not SPIRE-issued certificates | recorded | identity, TLS host or SVID rule change |
| S20 | The `kafka-admin` source creates, describes, lists and deletes topics on a real Kafka 3.9.1 KRaft broker in the default build; a dry run is the broker's own `validateOnly` check, creates nothing, and an impossible replication factor is refused by the broker. | `KafkaAdminToolSource`; `ExampleConfigsTest.kafkaConnectAndAdminClient` with `RealKafkaBroker` | real broker in its own JVM from `aegis-validation-kafka-server` | recorded | Kafka version or kafka-admin source change |
| G01 | `hooks[].type: project-governance` enforces evidence references for configured high-impact actions and denies protected resources. | `ProjectGovernanceGuardrail`; `ProjectGovernanceGuardrailTest`, and `ApacheProjectGovernanceProfileTest` for the profile build and tool visibility | deterministic hook tests; profile built in a temporary directory | recorded | guardrail setting, hook or profile change |
| S21 | The historical own-host Keycloak run reportedly gave each caller a per-user RFC 8693 backend token with no inbound-token forwarding, fallback, or token journaling. Current stricter token parsing postdates that run. Knox does not bind the required verified subject token and fails closed. | `TokenExchangeCredentialsTest`; `examples/adopters/token-exchange/keycloak_e2e.py` ([evidence](TOKEN-EXCHANGE-KEYCLOAK.md)) | Keycloak 26.8.0 standard token exchange, own host; no immutable raw run artifact retained | recorded | credential provider, host binding or Keycloak version change |
| S22 | The `a2a` source offers an A2A 1.0 agent as one governed tool, applies the source credential, and enforces the card endpoint origin rule. | `A2aToolSourceTest`; `A2aAgentFrontDoorsTest` | agent on the official `a2a-sdk` 1.2.1, own host and Knox 3.0.0 | recorded | a2a source, A2A protocol or SDK version change |
| S23 | `--openapi-draft` produces a configuration that loads, with every tool `DESTRUCTIVE` and a deny-all policy, from the published Iceberg 1.10.1 REST document; a reviewed tool reaches the real catalog with the document's schema enforced. | `OpenApiDraftTest`, `OpenApiDraftCommandTest`, `OpenApiDraftIcebergTest` | Iceberg 1.10.1 `RESTCatalogServer` | recorded | generator or schema validator change |
| S24 | A remote schema `$ref` is never fetched and denies the call; local `$ref`s are enforced and cycles are bounded. | `SchemaRefTest` | deterministic | recorded | schema validator change |
| S25 | Optional `serverCatalog`: an offline Ed25519-signed register, verified before parsing, decides at startup which configured sources start. Unlisted or changed (source-digest mismatch) sources stop start-up; QUARANTINED or REVOKED sources are never constructed or discovered; only pinned tools are bound; pinning becomes signed-only (an inline or manifest pin the catalog does not carry stops start-up). A break-glass order under a separate key can only reduce capability by quarantining or revoking named sources for at most 24 hours, and an expired order refuses start-up. The gateway jar generates, signs and verifies both files offline. No admin route exists for either. Deterministic tests and the reported four-engine two-door runs are `recorded`; their target output exists only under ignored `target/` paths, and Spark Connect was not run with a catalog. Key custody remains the operator's. Signed serial rollback protection depends on the configured atomic state-store high-water mark; unnumbered same-key files remain signature-only. | `SignedServerCatalog`, `BreakGlassContainment`, `CatalogIntegrity`, `GatewayFactory`, `ServerCatalogCommands`; `SignedServerCatalogTest`, `ServerCatalogConfigTest`, `ServerCatalogFlowTest` (real own host), `AdminApiTest.noRouteRegistersABackendAtRunTime` | JDK Ed25519; real own host on loopback; real Flink 1.20.1, Iceberg 1.10.1, Spark 4.0.1 and Kafka 3.9.1 through the own host and stock Knox 3.0.0 (`FlinkFrontDoorsTest`, `IcebergFrontDoorsTest`, `SparkFrontDoorsTest`, `KafkaFrontDoorsTest`, [run](../VALIDATION.md#signed-server-catalog-and-break-glass-against-real-engines-2026-10-06-local-working-tree)) | recorded | catalog or order format, source digest, pin or acceptance semantics change |
| G02 | The reference PII, secrets and change-window hooks refuse before the backend sees the call, withhold a result carrying a card number, and a stopped hook makes the gateway deny. | `adopters/hooks/test_hooks.py`; `adopters/hooks/e2e_gateway.py` | gateway jar as a process, CPython `http.server` backend | recorded | hook contract or hook service change |
| G03 | Security properties S1-S31 that have deterministic tests have a documented focused-suite plan; the product threat model documents assets, DFD, STRIDE by zone, TM01-TM10, and residual risk. The reported 2026-10-05 result is not bound to this review candidate by immutable raw evidence, so it is not current verification. | [SECURITY.md](../SECURITY.md), [THREAT-MODEL.md](../THREAT-MODEL.md); focused suite and per-class catalogue in [SECURITY-VALIDATION.md](SECURITY-VALIDATION.md) | reported JDK 17.0.7 Maven surefire run, 227 selected tests, 0 reported failures (2026-10-05) | recorded | any S1-S31 control, host perimeter, approval, egress, audit or identity change; promote only with candidate-bound raw evidence |
| H11 | The Helm chart renders valid Kubernetes 1.33 manifests, refuses unsafe values, and its rendered configuration starts the gateway with the StatefulSet's own arguments. | `charts/aegis/ci/start_rendered.py`; helm lint, kubeconform | Helm 4.3.0, kubeconform 0.8.0; no cluster | recorded | chart or Dockerfile change |
