fix(security): hard production guard on insecure-TLS escape hatch + workflow perms + example SDK bump

Three security alerts on axonflow-sdk-java:

1. CodeQL java/insecure-trustmanager (#8, high) at HttpClientFactory.java.
   The trust-all path is an intentional, double-gated development escape
   hatch for self-signed certs (requires BOTH insecureSkipVerify(true) AND
   AXONFLOW_INSECURE_TLS env var). Rather than remove the dev affordance,
   this adds a hard production guard: when a production-like deployment
   environment is detected (ENVIRONMENT / AXONFLOW_ENVIRONMENT / APP_ENV /
   SPRING_PROFILES_ACTIVE / NODE_ENV / ... carrying a 'prod'/'production'
   token), the insecure path is REFUSED outright, TLS verification stays
   enabled, and a SECURITY error is logged naming the signalling variable.
   New tests prove the guard PREVENTS the insecure path (not just logs),
   handles compound values (prod,metrics), and does not false-positive on
   non-production values. Alert to be dismissed-by-design on #2711 now that
   the production path is belt-and-suspenders hardened. Real code change ->
   VERSION bumped 8.5.0 -> 8.5.1 + CHANGELOG.

2. CodeQL actions/missing-workflow-permissions (#9, med) on
   heartbeat-real-stack.yml: added a top-level least-privilege
   'permissions: contents: read' block (workflow only checks out + tests).
   Block kept identical to the axonflow-sdk-typescript fix for coherence.

3. Dependabot #2 (med): examples/wcp-retry-idempotency/pom.xml pinned a
   stale com.getaxonflow:axonflow-sdk 5.5.0 (vulnerable < 6.0.0); bumped to
   the current released 8.5.0.

Refs getaxonflow/axonflow-enterprise#2711

Signed-off-by: Saurabh Jain <saurabh.jain@getaxonflow.com>

Author: saurabhjain1592

.github/workflows/heartbeat-real-stack.yml

@@ -19,6 +19,12 @@ concurrency:
 env:
   AXONFLOW_TELEMETRY: 'off'
 
+# Least-privilege token: this workflow only checks out the repo and runs
+# tests. No write access to repo contents, packages, or pull requests is
+# required.
+permissions:
+  contents: read
+
 jobs:
   real-stack:
     name: real-stack ${{ matrix.os }}

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to the AxonFlow Java SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [8.5.1] - 2026-06-16: TLS security hardening (production guard)
+
+Patch release. No public API changes.
+
+### Security
+
+- **Hard production guard on the insecure-TLS escape hatch.**
+  `HttpClientFactory` already required BOTH `insecureSkipVerify(true)` on the
+  config builder AND the `AXONFLOW_INSECURE_TLS` environment variable before it
+  would disable TLS certificate verification (a development-only path for
+  self-signed certificates). It now additionally refuses to disable verification
+  whenever a production-like deployment environment is detected, even if both
+  gates are set. A production environment is signalled by any of a set of common
+  deployment environment variables (for example `ENVIRONMENT`,
+  `AXONFLOW_ENVIRONMENT`, `APP_ENV`, `SPRING_PROFILES_ACTIVE`, `NODE_ENV`)
+  carrying a `prod` or `production` token. When the guard trips, TLS certificate
+  verification remains enabled and a `SECURITY` error is logged naming the
+  signalling variable. This is belt-and-suspenders hardening; the development
+  escape hatch for local self-signed certificates is unchanged. Clears CodeQL
+  `java/insecure-trustmanager` (alert #8).
+
 ## [8.5.0] - 2026-06-09 — Decision Mode PEP: decide → fulfill → forward
 
 Adds the SDK analog of the platform PEP client (`platform/shared/pep`, ADR-056,

examples/wcp-retry-idempotency/pom.xml

@@ -22,7 +22,7 @@
         <dependency>
             <groupId>com.getaxonflow</groupId>
             <artifactId>axonflow-sdk</artifactId>
-            <version>5.5.0</version>
+            <version>8.5.0</version>
         </dependency>
     </dependencies>
 

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.getaxonflow</groupId>
     <artifactId>axonflow-sdk</artifactId>
-    <version>8.5.0</version>
+    <version>8.5.1</version>
     <packaging>jar</packaging>
 
     <name>AxonFlow Java SDK</name>

src/main/java/com/getaxonflow/sdk/util/HttpClientFactory.java

@@ -18,6 +18,8 @@
 import com.getaxonflow.sdk.AxonFlowConfig;
 import java.security.SecureRandom;
 import java.security.cert.X509Certificate;
+import java.util.Locale;
+import java.util.Set;
 import java.util.concurrent.TimeUnit;
 import javax.net.ssl.SSLContext;
 import javax.net.ssl.TrustManager;
@@ -40,6 +42,50 @@ public final class HttpClientFactory {
    */
   static final String INSECURE_TLS_ENV_VAR = "AXONFLOW_INSECURE_TLS";
 
+  /**
+   * Common deployment-environment variables inspected by {@link #detectedProductionEnvSignal()}. If
+   * any is set to a production token ({@code "prod"}/{@code "production"}, case-insensitive), the
+   * insecure TLS path is refused outright as a hard production guard, even when both {@code
+   * insecureSkipVerify(true)} and {@value #INSECURE_TLS_ENV_VAR} are set. This is
+   * belt-and-suspenders on top of the existing double-gate: the trust-all path is a
+   * development-only escape hatch for self-signed certificates and must never run in production,
+   * even by operator error.
+   */
+  private static final String[] DEPLOYMENT_ENV_VARS = {
+    "AXONFLOW_ENVIRONMENT",
+    "AXONFLOW_ENV",
+    "ENVIRONMENT",
+    "APP_ENV",
+    "APPLICATION_ENV",
+    "DEPLOY_ENV",
+    "DEPLOYMENT_ENV",
+    "STAGE",
+    "SPRING_PROFILES_ACTIVE",
+    "NODE_ENV",
+    "RAILS_ENV",
+    "RACK_ENV",
+    "DJANGO_ENV",
+    "FLASK_ENV",
+    "ASPNETCORE_ENVIRONMENT",
+  };
+
+  /**
+   * Token delimiters used to split a deployment-environment variable's value before matching
+   * production tokens. Includes whitespace, comma/semicolon/colon (e.g. {@code
+   * SPRING_PROFILES_ACTIVE=prod,metrics}) AND hyphen/underscore/dot/slash so common compound names
+   * such as {@code production-us}, {@code prod_west} or {@code us/east/prod} are tokenised
+   * correctly.
+   */
+  private static final String ENV_VALUE_TOKEN_DELIMITERS = "[\\s,;:._/-]+";
+
+  /**
+   * Tokens that, when they immediately precede a {@code prod}/{@code production} token, negate it
+   * so the guard does NOT trip. This keeps non-production labels such as {@code non-prod}, {@code
+   * not-prod} and {@code pre-prod} (which tokenise to {@code [non, prod]} etc.) usable with the
+   * development escape hatch.
+   */
+  private static final Set<String> NEGATION_PREFIXES = Set.of("non", "not", "pre", "no");
+
   private HttpClientFactory() {
     // Utility class
   }
@@ -65,7 +111,23 @@ public static OkHttpClient create(AxonFlowConfig config) {
 
     if (config.isInsecureSkipVerify()) {
       if (isInsecureTlsEnvVarEnabled()) {
-        configureInsecureSsl(builder);
+        String productionSignal = detectedProductionEnvSignal();
+        if (productionSignal != null) {
+          // Hard production guard: refuse to disable TLS verification when a production-like
+          // deployment environment is detected, even though both gates were set. Keep the default
+          // (verifying) TrustManager in place.
+          logger.error(
+              "*** SECURITY *** insecureSkipVerify(true) and {}=true were both set, but a "
+                  + "production-like deployment environment was detected ({}). REFUSING to disable "
+                  + "TLS certificate verification. The insecure trust-all path is a development-only "
+                  + "escape hatch for self-signed certificates and MUST NOT run in production. TLS "
+                  + "certificate verification REMAINS ENABLED. Unset the production environment "
+                  + "signal (or run against a non-production environment) to use insecureSkipVerify.",
+              INSECURE_TLS_ENV_VAR,
+              productionSignal);
+        } else {
+          configureInsecureSsl(builder);
+        }
       } else {
         logger.warn(
             "insecureSkipVerify(true) was set on AxonFlowConfig but environment variable {} is "
@@ -157,4 +219,50 @@ static boolean isInsecureTlsEnvVarEnabled() {
     }
     return "true".equalsIgnoreCase(value) || "1".equals(value);
   }
+
+  /**
+   * Returns a human-readable {@code "VAR=value"} description of the first {@link
+   * #DEPLOYMENT_ENV_VARS deployment environment variable} that signals a production-like
+   * environment, or {@code null} if none do.
+   *
+   * <p>A variable signals production when any token of its value (split on whitespace, comma,
+   * semicolon, colon, hyphen, underscore, dot or slash) equals (case-insensitively) {@code "prod"}
+   * or {@code "production"}. Tokenising on those delimiters handles compound settings such as
+   * {@code SPRING_PROFILES_ACTIVE=prod,metrics} and {@code ENVIRONMENT=production-us}. A {@code
+   * prod}/{@code production} token immediately preceded by a {@link #NEGATION_PREFIXES negation
+   * prefix} (for example {@code non-prod} or {@code pre-prod}) does NOT count, so non-production
+   * labels remain usable with the development escape hatch.
+   *
+   * <p>Package-private to allow test verification.
+   */
+  static String detectedProductionEnvSignal() {
+    for (String var : DEPLOYMENT_ENV_VARS) {
+      String value = System.getenv(var);
+      if (value == null || value.isEmpty()) {
+        continue;
+      }
+      String[] tokens = value.toLowerCase(Locale.ROOT).split(ENV_VALUE_TOKEN_DELIMITERS);
+      for (int i = 0; i < tokens.length; i++) {
+        if (!tokens[i].equals("prod") && !tokens[i].equals("production")) {
+          continue;
+        }
+        if (i > 0 && NEGATION_PREFIXES.contains(tokens[i - 1])) {
+          // Negated form such as non-prod / pre-prod: not a production signal.
+          continue;
+        }
+        return var + "=" + value;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Returns {@code true} if any common deployment environment variable signals a production-like
+   * environment. Used as a hard production guard: even when both {@code insecureSkipVerify(true)}
+   * and {@value #INSECURE_TLS_ENV_VAR} are set, TLS certificate verification is NOT disabled in a
+   * production-like environment. Package-private to allow test verification.
+   */
+  static boolean isProductionLikeEnvironment() {
+    return detectedProductionEnvSignal() != null;
+  }
 }

src/test/java/com/getaxonflow/sdk/util/HttpClientFactoryTest.java

@@ -130,7 +130,10 @@ void shouldActivateInsecurePathWhenBothGatesArePresent() {
     // (covered by sibling tests). If either gate stops being required, this test will still
     // pass — the gating behaviour is asserted in the negative-path tests.
     AxonFlowConfig config =
-        AxonFlowConfig.builder().agentUrl("https://localhost:8080").insecureSkipVerify(true).build();
+        AxonFlowConfig.builder()
+            .agentUrl("https://localhost:8080")
+            .insecureSkipVerify(true)
+            .build();
 
     OkHttpClient client = HttpClientFactory.create(config);
 
@@ -168,8 +171,7 @@ void shouldKeepDefaultPathWhenOnlyEnvVarIsSet() {
     // Complementary negative path: env var alone, without insecureSkipVerify(true), must
     // keep the default safe TrustManager and OkHostnameVerifier. The double-gate is symmetric:
     // BOTH must be present — neither alone activates the insecure path.
-    AxonFlowConfig config =
-        AxonFlowConfig.builder().agentUrl("https://localhost:8080").build();
+    AxonFlowConfig config = AxonFlowConfig.builder().agentUrl("https://localhost:8080").build();
 
     OkHttpClient client = HttpClientFactory.create(config);
 
@@ -178,4 +180,122 @@ void shouldKeepDefaultPathWhenOnlyEnvVarIsSet() {
         .as("default hostname verifier must remain when only env var is set")
         .contains("OkHostnameVerifier");
   }
+
+  @Test
+  @DisplayName(
+      "should REFUSE the insecure TLS path when both gates are set but a production environment "
+          + "is detected (hard production guard)")
+  @SetEnvironmentVariable(key = "AXONFLOW_INSECURE_TLS", value = "true")
+  @SetEnvironmentVariable(key = "ENVIRONMENT", value = "production")
+  void shouldRefuseInsecurePathInProductionEnvironment() {
+    // Belt-and-suspenders: even with BOTH insecureSkipVerify(true) AND AXONFLOW_INSECURE_TLS=true,
+    // a production-like deployment environment must hard-refuse the trust-all path. This asserts
+    // the guard actually PREVENTS the insecure path (not merely logs): the default verifying
+    // hostname verifier MUST remain installed.
+    AxonFlowConfig config =
+        AxonFlowConfig.builder()
+            .agentUrl("https://localhost:8080")
+            .insecureSkipVerify(true)
+            .build();
+
+    OkHttpClient client = HttpClientFactory.create(config);
+
+    assertThat(client).isNotNull();
+
+    // Definitive proof the insecure path was refused: the insecure path installs the permissive
+    // `(hostname, session) -> true` verifier (a synthetic lambda whose class name does NOT contain
+    // "OkHostnameVerifier"). Seeing OkHttp's default verifier means the trust-all path never ran.
+    assertThat(client.hostnameVerifier().getClass().getName())
+        .as(
+            "production guard must keep the default verifying hostname verifier, refusing trust-all")
+        .contains("OkHostnameVerifier");
+
+    // Parity with a plain default client: the guard must leave the SAME verifier type in place as a
+    // config that never requested insecureSkipVerify at all. (OkHttp lazily builds a fresh default
+    // SSLSocketFactory per client, so the socket-factory instances are NOT identity-equal even on
+    // the safe path; the verifier type is the stable, meaningful signal here.)
+    AxonFlowConfig defaultConfig =
+        AxonFlowConfig.builder().agentUrl("https://localhost:8080").build();
+    OkHttpClient defaultClient = HttpClientFactory.create(defaultConfig);
+    assertThat(client.hostnameVerifier().getClass())
+        .as("production guard must leave the default verifier type in place")
+        .isEqualTo(defaultClient.hostnameVerifier().getClass());
+  }
+
+  @Test
+  @DisplayName("production-guard helper should be false in a clean (non-production) environment")
+  void productionGuardShouldBeFalseByDefault() {
+    // The standard CI/dev shell sets none of the inspected deployment env vars to a production
+    // token; if this fails, the test environment is mislabelled as production.
+    assertThat(HttpClientFactory.isProductionLikeEnvironment())
+        .as("no production signal should be present in a clean test environment")
+        .isFalse();
+    assertThat(HttpClientFactory.detectedProductionEnvSignal()).isNull();
+  }
+
+  @Test
+  @DisplayName("production-guard helper should detect ENVIRONMENT=production")
+  @SetEnvironmentVariable(key = "ENVIRONMENT", value = "production")
+  void productionGuardShouldDetectEnvironmentProduction() {
+    assertThat(HttpClientFactory.isProductionLikeEnvironment()).isTrue();
+    assertThat(HttpClientFactory.detectedProductionEnvSignal()).isEqualTo("ENVIRONMENT=production");
+  }
+
+  @Test
+  @DisplayName(
+      "production-guard helper should detect a compound SPRING_PROFILES_ACTIVE=prod,metrics")
+  @SetEnvironmentVariable(key = "SPRING_PROFILES_ACTIVE", value = "prod,metrics")
+  void productionGuardShouldDetectCompoundSpringProfile() {
+    // Compound, delimiter-separated values must be tokenised so a 'prod' token is still caught.
+    assertThat(HttpClientFactory.isProductionLikeEnvironment()).isTrue();
+    assertThat(HttpClientFactory.detectedProductionEnvSignal())
+        .isEqualTo("SPRING_PROFILES_ACTIVE=prod,metrics");
+  }
+
+  @Test
+  @DisplayName("production-guard helper should NOT trip on a non-production value")
+  @SetEnvironmentVariable(key = "ENVIRONMENT", value = "development")
+  void productionGuardShouldNotTripOnNonProductionValue() {
+    // A non-production environment must still allow the development escape hatch: the guard must
+    // not false-positive on substrings like 'reproduction' or unrelated values.
+    assertThat(HttpClientFactory.isProductionLikeEnvironment()).isFalse();
+    assertThat(HttpClientFactory.detectedProductionEnvSignal()).isNull();
+  }
+
+  @Test
+  @DisplayName("production-guard helper should detect a hyphen-delimited ENVIRONMENT=production-us")
+  @SetEnvironmentVariable(key = "ENVIRONMENT", value = "production-us")
+  void productionGuardShouldDetectHyphenDelimitedProductionName() {
+    // AxonFlow's own deployments use hyphen-delimited names like 'axonflow-production-us'; the
+    // tokeniser must split on '-' so the embedded production token is caught.
+    assertThat(HttpClientFactory.isProductionLikeEnvironment()).isTrue();
+    assertThat(HttpClientFactory.detectedProductionEnvSignal())
+        .isEqualTo("ENVIRONMENT=production-us");
+  }
+
+  @Test
+  @DisplayName("production-guard helper should detect an underscore-delimited APP_ENV=prod_west")
+  @SetEnvironmentVariable(key = "APP_ENV", value = "prod_west")
+  void productionGuardShouldDetectUnderscoreDelimitedProdName() {
+    assertThat(HttpClientFactory.isProductionLikeEnvironment()).isTrue();
+    assertThat(HttpClientFactory.detectedProductionEnvSignal()).isEqualTo("APP_ENV=prod_west");
+  }
+
+  @Test
+  @DisplayName("production-guard helper should NOT trip on a negated ENVIRONMENT=non-prod")
+  @SetEnvironmentVariable(key = "ENVIRONMENT", value = "non-prod")
+  void productionGuardShouldNotTripOnNegatedNonProd() {
+    // 'non-prod' tokenises to [non, prod]; the 'non' negation prefix must keep the development
+    // escape hatch usable in a non-production environment.
+    assertThat(HttpClientFactory.isProductionLikeEnvironment()).isFalse();
+    assertThat(HttpClientFactory.detectedProductionEnvSignal()).isNull();
+  }
+
+  @Test
+  @DisplayName("production-guard helper should NOT trip on a negated SPRING profile pre-prod")
+  @SetEnvironmentVariable(key = "SPRING_PROFILES_ACTIVE", value = "pre-prod,metrics")
+  void productionGuardShouldNotTripOnNegatedPreProd() {
+    assertThat(HttpClientFactory.isProductionLikeEnvironment()).isFalse();
+    assertThat(HttpClientFactory.detectedProductionEnvSignal()).isNull();
+  }
 }