Add runnable OpenResty-style header policy example

Author: eldryoth

CHANGELOG.md

@@ -16,6 +16,8 @@ behavior when the change improves security or project direction.
   denial, and fail-closed plugin traps.
 - Add a dedicated Wasm policy-example smoke to the human test starter and the
   opt-in Wasm release gate.
+- Add the checked-in nginx Lua/OpenResty-style bounded request/response header
+  policy and config example, compiled directly by its real listener tests.
 
 ### Security
 

crates/fluxheim-config/src/config_tests_wasm.rs

@@ -44,6 +44,17 @@ fn irules_access_policy_example_config_validates() {
     assert_eq!(config.validate(), Ok(()));
 }
 
+#[cfg(feature = "wasm")]
+#[test]
+fn openresty_header_policy_example_config_validates() {
+    let config: Config = toml::from_str(include_str!(
+        "../../../examples/wasm/openresty-header-policy.toml"
+    ))
+    .unwrap();
+
+    assert_eq!(config.validate(), Ok(()));
+}
+
 #[cfg(feature = "wasm")]
 fn proxy_preview_wasm_config(plugin_fields: &str) -> Config {
     toml::from_str(&format!(

crates/fluxheim-server/src/native_http1_route_proxy_tests/wasm.rs

@@ -477,8 +477,9 @@ async fn native_wasm_cache_admission_budget_is_fair_across_vhosts() {
 }
 
 #[tokio::test]
-async fn native_wasm_request_and_response_headers_use_bounded_host_calls() {
-    let fixture = WasmRouteFixture::new(&[("headers", WasmPluginBody::HeaderPolicy)]);
+async fn native_wasm_openresty_header_policy_example_uses_bounded_host_calls() {
+    let fixture =
+        WasmRouteFixture::new(&[("headers", WasmPluginBody::OpenRestyHeaderPolicyExample)]);
     let upstream = upstream_expect_policy_header("/item").await;
     let mut config = fixture
         .config_with_attachments(upstream, vec![wasm_attachment_all("headers", "route", 100)]);
@@ -1167,7 +1168,7 @@ async fn native_wasm_cache_store_can_set_bounded_stored_response_header() {
 async fn native_wasm_cross_family_chain_runs_in_order_with_cache_hit_metadata() {
     let fixture = WasmRouteFixture::new(&[
         ("access", WasmPluginBody::Decision(1)),
-        ("headers", WasmPluginBody::HeaderPolicy),
+        ("headers", WasmPluginBody::OpenRestyHeaderPolicyExample),
         ("router", WasmPluginBody::RouteDecision),
         ("cache_key", WasmPluginBody::CacheLookupDeviceKey),
         ("cache_store", WasmPluginBody::CacheStoreHeader),
@@ -1746,7 +1747,8 @@ async fn native_wasm_cache_store_deny_wins_over_earlier_skip() {
 #[cfg(feature = "php-fpm")]
 #[tokio::test]
 async fn native_wasm_response_headers_apply_to_php_fpm_fallback() {
-    let fixture = WasmRouteFixture::new(&[("headers", WasmPluginBody::HeaderPolicy)]);
+    let fixture =
+        WasmRouteFixture::new(&[("headers", WasmPluginBody::OpenRestyHeaderPolicyExample)]);
     let fpm = fastcgi_responder(
         b"Status: 200 OK\r\nContent-Type: text/plain\r\nX-Powered-By: php\r\n\r\nphp-policy",
     )
@@ -1900,7 +1902,7 @@ impl WasmRouteFixture {
 enum WasmPluginBody {
     Decision(i32),
     IrulesAccessPolicyExample,
-    HeaderPolicy,
+    OpenRestyHeaderPolicyExample,
     ForbiddenHeader,
     RouteDecision,
     CacheLookup,
@@ -1942,43 +1944,8 @@ impl WasmPluginBody {
             Self::IrulesAccessPolicyExample => {
                 include_str!("../../../../examples/wasm/irules-access-policy.wat").to_owned()
             }
-            Self::HeaderPolicy => {
-                r#"
-                (module
-                  (import "fluxheim_policy_v1" "context" (func $context (param i32 i32) (result i32)))
-                  (import "fluxheim_policy_v1" "set_request_header" (func $set_request_header (param i32 i32) (result i32)))
-                  (import "fluxheim_policy_v1" "set_response_header" (func $set_response_header (param i32 i32) (result i32)))
-                  (import "fluxheim_policy_v1" "remove_response_header" (func $remove_response_header (param i32 i32) (result i32)))
-                  (func (export "fluxheim_request_headers") (result i32)
-                    i32.const 1
-                    i32.const 0
-                    call $context
-                    i32.const 3
-                    i32.eq
-                    if
-                      i32.const 1
-                      i32.const 4
-                      call $set_request_header
-                      drop
-                    else
-                      i32.const 1
-                      i32.const 1
-                      call $set_request_header
-                      drop
-                    end
-                    i32.const 0)
-                  (func (export "fluxheim_response_headers") (result i32)
-                    i32.const 2
-                    i32.const 4
-                    call $set_response_header
-                    drop
-                    i32.const 3
-                    i32.const 0
-                    call $remove_response_header
-                    drop
-                    i32.const 0))
-                "#
-                .to_owned()
+            Self::OpenRestyHeaderPolicyExample => {
+                include_str!("../../../../examples/wasm/openresty-header-policy.wat").to_owned()
             }
             Self::ForbiddenHeader => {
                 r#"
@@ -2358,7 +2325,7 @@ fn wasm_plugin(root: &Path, name: &str, body: WasmPluginBody) -> fluxheim_config
 
 fn wasm_plugin_phases(body: WasmPluginBody) -> Vec<fluxheim_config::WasmPluginPhase> {
     match body {
-        WasmPluginBody::HeaderPolicy => vec![
+        WasmPluginBody::OpenRestyHeaderPolicyExample => vec![
             fluxheim_config::WasmPluginPhase::RequestHeaders,
             fluxheim_config::WasmPluginPhase::ResponseHeaders,
         ],

docs/wasm-policy-example-parity.md

@@ -92,6 +92,13 @@ coverage is in
 mutation IDs. The ABI remains symbolic and does not expose raw sensitive
 headers or bodies.
 
+The `v1.7.9` operator example is checked in as
+`examples/wasm/openresty-header-policy.wat` with a complete config fixture. The
+shared policy-example smoke compiles that exact source and proves the origin
+receives `x-policy-tier: gold`, the client receives
+`x-fluxheim-policy-branch: gold`, upstream `x-powered-by` is removed, and an
+unknown header mutation ID fails closed before origin dispatch.
+
 ### HAProxy Lua/SPOE-Style Routing And Load-Balancer Policy
 
 Capability target:

examples/wasm/README.md

@@ -19,6 +19,18 @@ module receives no raw headers, body, filesystem, network, admin-token, or TLS
 secret capability. Use native route and access configuration for classification
 instead of attempting arbitrary parsing inside the plugin.
 
+`openresty-header-policy.wat` and `openresty-header-policy.toml` demonstrate
+the nginx Lua/OpenResty-style header-policy mapping. On the configured `/gold/`
+route, the module reads only Fluxheim's bounded path-class ID, adds the
+allow-listed `x-policy-tier: gold` request header, removes the allow-listed
+upstream `x-powered-by` response header, and adds
+`x-fluxheim-policy-branch: gold` to the client response.
+
+The guest cannot read raw `Authorization`, `Cookie`, or `Set-Cookie` values and
+cannot create arbitrary names or values. Unknown IDs, duplicate/oversized
+mutations, traps, timeouts, and admission failures follow the configured fail
+mode; security-sensitive examples use `fail-closed`.
+
 `cache-lookup-policy.wat` and `cache-store-policy.wat` demonstrate the bounded
 1.7.5 cache-policy ABI:
 

examples/wasm/openresty-header-policy.toml

@@ -0,0 +1,43 @@
+# Compile openresty-header-policy.wat to the configured .wasm path and replace
+# the sha256 placeholder with the compiled module digest before use.
+
+[wasm]
+enabled = true
+plugin_roots = ["/etc/fluxheim/plugins"]
+max_total_concurrent_executions = 256
+
+[[wasm.plugins]]
+name = "openresty_header_policy"
+path = "/etc/fluxheim/plugins/openresty-header-policy.wasm"
+sha256 = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+abi = "fluxheim-policy-v1"
+host_call_namespace = "fluxheim-policy-v1"
+phases = ["request-headers", "response-headers"]
+fail_mode = "fail-closed"
+
+[wasm.plugins.limits]
+max_module_bytes = "1MiB"
+max_memory_bytes = "16MiB"
+max_table_elements = 10000
+fuel = 5000000
+timeout_ms = 50
+compile_timeout_ms = 500
+
+[[wasm.attachments]]
+plugin = "openresty_header_policy"
+vhost = "example"
+route = "gold"
+priority = 100
+phases = ["request-headers", "response-headers"]
+
+[[vhosts]]
+name = "example"
+hosts = ["example.com"]
+
+[[vhosts.routes]]
+name = "gold"
+path_prefix = "/gold/"
+strip_prefix = "/gold"
+
+[vhosts.routes.proxy]
+upstreams = ["127.0.0.1:3000"]

examples/wasm/openresty-header-policy.wat

@@ -0,0 +1,44 @@
+(module
+  (import "fluxheim_policy_v1" "context"
+    (func $context (param i32 i32) (result i32)))
+  (import "fluxheim_policy_v1" "set_request_header"
+    (func $set_request_header (param i32 i32) (result i32)))
+  (import "fluxheim_policy_v1" "set_response_header"
+    (func $set_response_header (param i32 i32) (result i32)))
+  (import "fluxheim_policy_v1" "remove_response_header"
+    (func $remove_response_header (param i32 i32) (result i32)))
+
+  (func (export "fluxheim_request_headers") (result i32)
+    ;; Context field 1 is Fluxheim's bounded path class. Class 3 is /gold.
+    i32.const 1
+    i32.const 0
+    call $context
+    i32.const 3
+    i32.eq
+    if
+      ;; Header ID 1 is x-policy-tier; value ID 4 is gold.
+      i32.const 1
+      i32.const 4
+      call $set_request_header
+      drop
+    else
+      ;; Value ID 1 is standard.
+      i32.const 1
+      i32.const 1
+      call $set_request_header
+      drop
+    end
+    i32.const 0)
+
+  (func (export "fluxheim_response_headers") (result i32)
+    ;; Header ID 2 is x-fluxheim-policy-branch; value ID 4 is gold.
+    i32.const 2
+    i32.const 4
+    call $set_response_header
+    drop
+    ;; Removable response-header ID 3 is x-powered-by.
+    i32.const 3
+    i32.const 0
+    call $remove_response_header
+    drop
+    i32.const 0))

packaging/rpm/fluxheim.spec

@@ -157,6 +157,7 @@ fi
 * Sun Jul 12 2026 Fluxheim Maintainers <1921261+eldryoth@users.noreply.github.com> - 1.7.9-1
 - Start documented and runnable Wasm migration-example parity work.
 - Add the F5 iRules-style route access example and real listener smoke.
+- Add the nginx Lua/OpenResty-style bounded header-policy example.
 - Harden snapshot opens against pathname races and isolate corruption fixtures
   behind safe store primitives.
 

release-notes/RELEASE_NOTES_1.7.9.md

@@ -15,6 +15,10 @@ products.
   closed.
 - Add `scripts/smoke_wasm_policy_examples.sh` to `scripts/test_starter.py` and
   the opt-in Wasm release gate.
+- Add a checked-in nginx Lua/OpenResty-style header policy and complete config
+  fixture. Live coverage proves the allow-listed origin request mutation,
+  client response mutation, upstream-header removal, and fail-closed rejection
+  of unknown mutation IDs.
 
 ## Security
 

scripts/smoke_wasm_policy_examples.sh

@@ -5,5 +5,9 @@ cargo test --locked -p fluxheim-server --features wasm \
     native_wasm_irules_policy_example_allows_public_and_denies_admin
 cargo test --locked -p fluxheim-server --features wasm \
     native_wasm_access_decision_fails_closed_on_trap
+cargo test --locked -p fluxheim-server --features wasm \
+    native_wasm_openresty_header_policy_example_uses_bounded_host_calls
+cargo test --locked -p fluxheim-server --features wasm \
+    native_wasm_forbidden_header_mutation_fails_closed
 
 echo "wasm policy examples smoke: ok"