feat(filter): add peer identity trust enforcement

docs/filters/http/security/peer_identity_trust.md

@@ -0,0 +1,33 @@
+<!-- Generated by: cargo xtask generate-filter-docs -->
+<!-- Do not edit manually -->
+
+# `peer_identity_trust`
+
+Validates that the downstream mTLS peer identity matches a configured trusted peer before allowing the request to continue.
+
+## Configuration Notes
+
+Requests without a verified peer identity are rejected with 403. Requests with a peer identity that does not match any trusted peer entry are also rejected with 403.
+
+Each trusted peer entry specifies one or more match fields. All configured fields on an entry must match the peer identity for that entry to accept the request.
+
+`cert_digest` (the SHA-256 hex digest of the peer certificate) is the strongest static match field. `organization` and `serial_number` are weaker and are primarily useful for bootstrap or controlled test configurations where cert digests are not known ahead of time. SAN/SPIFFE identity matching is planned for a follow-up.
+
+## Configuration
+
+| Field | Type | Required | Description |
+|-------|------|---------|-------------|
+| `trusted_peers` | TrustedPeerConfig[] | yes | Trusted peer entries. |
+| `trusted_peers[].cert_digest` | string | no | Lowercase hex-encoded SHA-256 certificate digest. |
+| `trusted_peers[].organization` | string | no | X.509 subject organization (`O=` field). Weaker than certificate digest — useful for bootstrap and controlled test configurations where cert digests are not known ahead of time. |
+| `trusted_peers[].serial_number` | string | no | Certificate serial number. |
+
+## Example
+
+```yaml
+filter: peer_identity_trust
+trusted_peers:
+  - cert_digest: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+  - cert_digest: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+    organization: example-org
+```

docs/filters/reference.md

@@ -30,6 +30,7 @@ Built-in filters organized by protocol and category.
 | [`forwarded_headers`](http/security/forwarded_headers.md) | - | Injects `X-Forwarded-For`, `X-Forwarded-Proto`, and `X-Forwarded-Host` headers into upstream requests. |
 | [`guardrails`](http/security/guardrails.md) | - | Rejects requests matching string, regex, or PII rules against headers and/or body content. |
 | [`ip_acl`](http/security/ip_acl.md) | - | IP-based access control filter. |
+| [`peer_identity_trust`](http/security/peer_identity_trust.md) | - | Validates that the downstream mTLS peer identity matches a configured trusted peer before allowing the request to continue. |
 | [`policy`](http/security/policy.md) | `cpex-policy-engine` | Embeds the CPEX policy engine in-process to enforce multi-source JWT identity, APL route policy, RFC 8693 token exchange, PII scanning, audit emission, and (under `body_access: read_write`) request / response body rewriting. |
 
 ## HTTP / Traffic Management

filter/src/builtins/http/mod.rs

@@ -16,7 +16,7 @@ pub use payload_processing::{CompressionFilter, JsonBodyFieldFilter, JsonRpcFilt
 pub use security::PolicyFilter;
 pub use security::{
     ContainsValue, CorsFilter, CredentialInjectionFilter, CsrfFilter, DisallowedOriginMode, ForwardedHeadersFilter,
-    GuardrailsAction, GuardrailsFilter, IpAclFilter, PiiKind, RuleTargetKind,
+    GuardrailsAction, GuardrailsFilter, IpAclFilter, PeerIdentityTrustFilter, PiiKind, RuleTargetKind,
 };
 pub use traffic_management::{
     CircuitBreakerFilter, EndpointSelectorFilter, GrpcDetectionFilter, LoadBalancerFilter, RateLimitFilter,

filter/src/builtins/http/security/mod.rs

@@ -2,8 +2,8 @@
 // Copyright (c) 2024 Praxis Contributors
 
 //! HTTP security filters: CORS, CSRF, IP access control, credential injection,
-//! forwarded-header injection, guardrails, and the (feature-gated) CPEX policy
-//! filter.
+//! forwarded-header injection, guardrails, mTLS ingress trust enforcement,
+//! and the (feature-gated) CPEX policy filter.
 
 mod cors;
 mod credential_injection;
@@ -13,6 +13,7 @@ mod guardrails;
 mod ip_acl;
 pub(crate) mod origin_matcher;
 pub(crate) mod origin_normalize;
+mod peer_identity_trust;
 #[cfg(feature = "cpex-policy-engine")]
 mod policy;
 
@@ -22,5 +23,6 @@ pub use csrf::CsrfFilter;
 pub use forwarded_headers::ForwardedHeadersFilter;
 pub use guardrails::{ContainsValue, GuardrailsAction, GuardrailsFilter, PiiKind, RuleTargetKind};
 pub use ip_acl::IpAclFilter;
+pub use peer_identity_trust::PeerIdentityTrustFilter;
 #[cfg(feature = "cpex-policy-engine")]
 pub use policy::PolicyFilter;