feat(java): support encrypted CDN resolver state

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nicklasl

openfeature-provider/java/src/main/java/com/spotify/confidence/sdk/FlagsAdminStateFetcher.java

@@ -25,6 +25,7 @@ class FlagsAdminStateFetcher implements AccountStateProvider {
       "https://confidence-resolver-state-cdn.spotifycdn.com/";
 
   private final String clientSecret;
+  private final String encryptionKey;
   private final HttpClientFactory httpClientFactory;
   // ETag for conditional GETs of resolver state
   private final AtomicReference<String> etagHolder = new AtomicReference<>();
@@ -33,19 +34,34 @@ class FlagsAdminStateFetcher implements AccountStateProvider {
           com.spotify.confidence.sdk.flags.admin.v1.ResolverState.newBuilder()
               .build()
               .toByteArray());
+  private final AtomicReference<byte[]> rawCdnBytesHolder = new AtomicReference<>();
   private String accountId = "";
 
   public FlagsAdminStateFetcher(String clientSecret, HttpClientFactory httpClientFactory) {
+    this(clientSecret, httpClientFactory, null);
+  }
+
+  public FlagsAdminStateFetcher(
+      String clientSecret, HttpClientFactory httpClientFactory, String encryptionKey) {
     this.clientSecret = clientSecret;
     this.httpClientFactory = httpClientFactory;
+    this.encryptionKey = encryptionKey;
   }
 
   public AtomicReference<byte[]> rawStateHolder() {
     return rawResolverStateHolder;
   }
 
+  public byte[] rawCdnBytes() {
+    return rawCdnBytesHolder.get();
+  }
+
   @Override
   public byte[] provide() {
+    final byte[] cdnBytes = rawCdnBytesHolder.get();
+    if (cdnBytes != null) {
+      return cdnBytes;
+    }
     return rawResolverStateHolder.get();
   }
 
@@ -64,32 +80,34 @@ public void reload() {
   }
 
   private void fetchAndUpdateStateIfChanged() {
-    // Build CDN URL using SHA256 hash of client secret
-    final var cdnUrl = CDN_BASE_URL + sha256Hex(clientSecret);
+    final var hash = sha256Hex(clientSecret);
+    final boolean useEncrypted = encryptionKey != null && !encryptionKey.isEmpty();
+    final var cdnUrl = CDN_BASE_URL + (useEncrypted ? hash + ".enc" : hash);
     try {
       final HttpURLConnection conn = httpClientFactory.create(cdnUrl);
       final String previousEtag = etagHolder.get();
       if (previousEtag != null) {
         conn.setRequestProperty("if-none-match", previousEtag);
       }
       if (conn.getResponseCode() == 304) {
-        // Not modified
         return;
       }
       final String etag = conn.getHeaderField("etag");
       try (final InputStream stream = conn.getInputStream()) {
         final byte[] bytes = stream.readAllBytes();
 
-        // Parse SetResolverStateRequest from CDN response
-        final var stateRequest =
-            com.spotify.confidence.sdk.wasm.Messages.SetResolverStateRequest.parseFrom(bytes);
-        this.accountId = stateRequest.getAccountId();
-
-        // Store the state bytes (already in bytes format)
-        rawResolverStateHolder.set(stateRequest.getState().toByteArray());
+        if (useEncrypted) {
+          rawCdnBytesHolder.set(bytes);
+        } else {
+          final var stateRequest =
+              com.spotify.confidence.sdk.wasm.Messages.SetResolverStateRequest.parseFrom(bytes);
+          this.accountId = stateRequest.getAccountId();
+          rawResolverStateHolder.set(stateRequest.getState().toByteArray());
+          rawCdnBytesHolder.set(null);
+        }
         etagHolder.set(etag);
       }
-      logger.info("Loaded resolver state for account={}, etag={}", accountId, etag);
+      logger.info("Loaded resolver state (encrypted={}, etag={})", useEncrypted, etag);
     } catch (IOException e) {
       throw new RuntimeException(e);
     }

openfeature-provider/java/src/main/java/com/spotify/confidence/sdk/LocalProviderConfig.java

@@ -11,6 +11,7 @@ public class LocalProviderConfig {
   private final HttpClientFactory httpClientFactory;
   private final boolean useRemoteMaterializationStore;
   private final int resolverPoolSize;
+  private final String encryptionKey;
 
   public LocalProviderConfig() {
     this(null, null);
@@ -36,11 +37,21 @@ public LocalProviderConfig(
       HttpClientFactory httpClientFactory,
       boolean useRemoteMaterializationStore,
       int resolverPoolSize) {
+    this(channelFactory, httpClientFactory, useRemoteMaterializationStore, resolverPoolSize, null);
+  }
+
+  private LocalProviderConfig(
+      ChannelFactory channelFactory,
+      HttpClientFactory httpClientFactory,
+      boolean useRemoteMaterializationStore,
+      int resolverPoolSize,
+      String encryptionKey) {
     this.channelFactory = channelFactory != null ? channelFactory : new DefaultChannelFactory();
     this.httpClientFactory =
         httpClientFactory != null ? httpClientFactory : new DefaultHttpClientFactory();
     this.useRemoteMaterializationStore = useRemoteMaterializationStore;
     this.resolverPoolSize = resolverPoolSize > 0 ? resolverPoolSize : DEFAULT_RESOLVER_POOL_SIZE;
+    this.encryptionKey = encryptionKey;
   }
 
   public ChannelFactory getChannelFactory() {
@@ -63,6 +74,11 @@ public int getResolverPoolSize() {
     return resolverPoolSize;
   }
 
+  /** Returns the hex-encoded AES-256 encryption key, or {@code null} if unset. */
+  public String getEncryptionKey() {
+    return encryptionKey;
+  }
+
   public static Builder builder() {
     return new Builder();
   }
@@ -72,6 +88,7 @@ public static class Builder {
     private HttpClientFactory httpClientFactory;
     private boolean useRemoteMaterializationStore;
     private int resolverPoolSize;
+    private String encryptionKey;
 
     public Builder channelFactory(ChannelFactory channelFactory) {
       this.channelFactory = channelFactory;
@@ -100,9 +117,19 @@ public Builder resolverPoolSize(int resolverPoolSize) {
       return this;
     }
 
+    /** Sets the hex-encoded AES-256 encryption key for decrypting CDN state. */
+    public Builder encryptionKey(String encryptionKey) {
+      this.encryptionKey = encryptionKey;
+      return this;
+    }
+
     public LocalProviderConfig build() {
       return new LocalProviderConfig(
-          channelFactory, httpClientFactory, useRemoteMaterializationStore, resolverPoolSize);
+          channelFactory,
+          httpClientFactory,
+          useRemoteMaterializationStore,
+          resolverPoolSize,
+          encryptionKey);
     }
   }
 }

openfeature-provider/java/src/main/java/com/spotify/confidence/sdk/LocalResolver.java

@@ -19,6 +19,8 @@ interface LocalResolver {
    */
   void setResolverState(byte[] state, String accountId, Sdk sdk);
 
+  void setEncryptedResolverState(byte[] encryptedState, byte[] encryptionKey, Sdk sdk);
+
   /**
    * Resolves flags. The returned stage completes when all resolution (including any store I/O for
    * materializations) has finished.

openfeature-provider/java/src/main/java/com/spotify/confidence/sdk/MaterializingResolver.java

@@ -167,6 +167,11 @@ public void setResolverState(byte[] state, String accountId, Sdk sdk) {
     delegate.setResolverState(state, accountId, sdk);
   }
 
+  @Override
+  public void setEncryptedResolverState(byte[] encryptedState, byte[] encryptionKey, Sdk sdk) {
+    delegate.setEncryptedResolverState(encryptedState, encryptionKey, sdk);
+  }
+
   @Override
   public void registerResolve(RegisterResolveRequest request) {
     delegate.registerResolve(request);

openfeature-provider/java/src/main/java/com/spotify/confidence/sdk/OpenFeatureLocalResolveProvider.java

@@ -64,6 +64,7 @@ public class OpenFeatureLocalResolveProvider implements FeatureProvider {
   private final AccountStateProvider stateProvider;
   private final AtomicReference<ProviderState> state =
       new AtomicReference<>(ProviderState.NOT_READY);
+  private final String encryptionKey;
   private volatile boolean initialized = false;
   private volatile byte[] lastStateBytes = null;
   @VisibleForTesting boolean forcedFetcherShutdown = false;
@@ -147,8 +148,11 @@ public OpenFeatureLocalResolveProvider(
   public OpenFeatureLocalResolveProvider(
       LocalProviderConfig config, String clientSecret, MaterializationStore materializationStore) {
     this.clientSecret = clientSecret;
+    this.encryptionKey = config.getEncryptionKey();
     this.materializationStore = materializationStore;
-    this.stateProvider = new FlagsAdminStateFetcher(clientSecret, config.getHttpClientFactory());
+    this.stateProvider =
+        new FlagsAdminStateFetcher(
+            clientSecret, config.getHttpClientFactory(), config.getEncryptionKey());
     final var wasmFlagLogger = new GrpcWasmFlagLogger(clientSecret, config.getChannelFactory());
     this.flagLogger = wasmFlagLogger;
     final int numInstances = PooledResolver.getNumInstances(config.getResolverPoolSize());
@@ -174,6 +178,7 @@ public OpenFeatureLocalResolveProvider(
       MaterializationStore materializationStore,
       WasmFlagLogger wasmFlagLogger) {
     this.clientSecret = clientSecret;
+    this.encryptionKey = null;
     this.materializationStore = materializationStore;
     this.stateProvider = accountStateProvider;
     this.flagLogger = wasmFlagLogger;
@@ -198,12 +203,19 @@ public void initialize(EvaluationContext evaluationContext) {
         new AtomicReference<>(stateProvider.provide());
     final AtomicReference<String> accountIdRef = new AtomicReference<>(stateProvider.accountId());
 
-    // Only initialize WASM and set READY if we got valid state (non-empty accountId)
-    if (!accountIdRef.get().isEmpty()) {
+    if (encryptionKey != null) {
+      final byte[] stateBytes = resolverStateProtobuf.get();
+      if (stateBytes != null && stateBytes.length > 0) {
+        resolver.setEncryptedResolverState(stateBytes, hexToBytes(encryptionKey), SDK);
+        initialized = true;
+        this.state.set(ProviderState.READY);
+      }
+    } else if (!accountIdRef.get().isEmpty()) {
       resolver.setResolverState(resolverStateProtobuf.get(), accountIdRef.get(), SDK);
       initialized = true;
       this.state.set(ProviderState.READY);
-    } else {
+    }
+    if (!initialized) {
       log.warn(
           "Initial state load failed, provider starting in NOT_READY state, serving default"
               + " values.");
@@ -245,22 +257,31 @@ private void scheduleStateRefresh(
             resolverStateProtobuf.set(stateProvider.provide());
             accountIdRef.set(stateProvider.accountId());
 
-            if (!accountIdRef.get().isEmpty()) {
+            final byte[] newState = resolverStateProtobuf.get();
+            final boolean hasState =
+                encryptionKey != null
+                    ? (newState != null && newState.length > 0)
+                    : !accountIdRef.get().isEmpty();
+            if (hasState) {
               if (!initialized) {
-                resolver.setResolverState(resolverStateProtobuf.get(), accountIdRef.get(), SDK);
-                lastStateBytes = resolverStateProtobuf.get();
+                if (encryptionKey != null) {
+                  resolver.setEncryptedResolverState(newState, hexToBytes(encryptionKey), SDK);
+                } else {
+                  resolver.setResolverState(newState, accountIdRef.get(), SDK);
+                }
+                lastStateBytes = newState;
                 initialized = true;
                 this.state.set(ProviderState.READY);
                 log.info("Provider recovered and is now READY");
               } else {
-                // Only push state into the wasm instances when it actually changed — the wasm
-                // execution inside setResolverState is expensive (runs across all pool slots).
-                final byte[] newState = resolverStateProtobuf.get();
                 if (!java.util.Arrays.equals(newState, lastStateBytes)) {
-                  resolver.setResolverState(newState, accountIdRef.get(), SDK);
+                  if (encryptionKey != null) {
+                    resolver.setEncryptedResolverState(newState, hexToBytes(encryptionKey), SDK);
+                  } else {
+                    resolver.setResolverState(newState, accountIdRef.get(), SDK);
+                  }
                   lastStateBytes = newState;
                 }
-                // Always flush logs regardless of state change.
                 resolver.flushAllLogs();
               }
             }
@@ -274,6 +295,10 @@ private void scheduleStateRefresh(
         TimeUnit.SECONDS);
   }
 
+  private static byte[] hexToBytes(String hex) {
+    return java.util.HexFormat.of().parseHex(hex);
+  }
+
   @Override
   public Metadata getMetadata() {
     return () -> "confidence-sdk-java-local";

openfeature-provider/java/src/main/java/com/spotify/confidence/sdk/PooledResolver.java

@@ -72,6 +72,11 @@ public void setResolverState(byte[] state, String accountId, Sdk sdk) {
     maintenance(lr -> lr.setResolverState(state, accountId, sdk));
   }
 
+  @Override
+  public void setEncryptedResolverState(byte[] encryptedState, byte[] encryptionKey, Sdk sdk) {
+    maintenance(lr -> lr.setEncryptedResolverState(encryptedState, encryptionKey, sdk));
+  }
+
   @Override
   public void flushAllLogs() {
     maintenance(LocalResolver::flushAllLogs);

openfeature-provider/java/src/main/java/com/spotify/confidence/sdk/RecoveringResolver.java

@@ -24,10 +24,13 @@ class RecoveringResolver implements LocalResolver {
 
   private record StateRecord(byte[] state, String accountId, Sdk sdk) {}
 
+  private record EncryptedStateRecord(byte[] encryptedState, byte[] encryptionKey, Sdk sdk) {}
+
   private final Supplier<LocalResolver> factory;
   private final AtomicReference<LocalResolver> current = new AtomicReference<>();
   private final AtomicBoolean broken = new AtomicBoolean(false);
   private final AtomicReference<StateRecord> lastState = new AtomicReference<>();
+  private final AtomicReference<EncryptedStateRecord> lastEncryptedState = new AtomicReference<>();
 
   RecoveringResolver(Supplier<LocalResolver> factory) {
     this.factory = factory;
@@ -41,8 +44,14 @@ private void startRecreate() {
               try {
                 final LocalResolver old = current.get();
                 final LocalResolver newResolver = factory.get();
+                final EncryptedStateRecord cachedEncrypted = lastEncryptedState.get();
                 final StateRecord cached = lastState.get();
-                if (cached != null) {
+                if (cachedEncrypted != null) {
+                  newResolver.setEncryptedResolverState(
+                      cachedEncrypted.encryptedState(),
+                      cachedEncrypted.encryptionKey(),
+                      cachedEncrypted.sdk());
+                } else if (cached != null) {
                   newResolver.setResolverState(cached.state(), cached.accountId(), cached.sdk());
                 }
                 current.set(newResolver);
@@ -84,12 +93,25 @@ public void setResolverState(byte[] state, String accountId, Sdk sdk) {
     try {
       current.get().setResolverState(state, accountId, sdk);
       lastState.set(new StateRecord(state, accountId, sdk));
+      lastEncryptedState.set(null);
     } catch (ChicoryException e) {
       handleFailure("setResolverState", e);
       throw e;
     }
   }
 
+  @Override
+  public void setEncryptedResolverState(byte[] encryptedState, byte[] encryptionKey, Sdk sdk) {
+    try {
+      current.get().setEncryptedResolverState(encryptedState, encryptionKey, sdk);
+      lastEncryptedState.set(new EncryptedStateRecord(encryptedState, encryptionKey, sdk));
+      lastState.set(null);
+    } catch (ChicoryException e) {
+      handleFailure("setEncryptedResolverState", e);
+      throw e;
+    }
+  }
+
   @Override
   public CompletionStage<ResolveProcessResponse> resolveProcess(ResolveProcessRequest request) {
     try {

openfeature-provider/java/src/main/java/com/spotify/confidence/sdk/WasmLocalResolver.java

@@ -52,6 +52,7 @@ class WasmLocalResolver implements LocalResolver {
 
   // api
   private final ExportFunction wasmMsgGuestSetResolverState;
+  private final ExportFunction wasmMsgGuestSetEncryptedResolverState;
   private final ExportFunction wasmMsgGuestRegisterResolve;
   private final ExportFunction wasmMsgBoundedFlushLogs;
   private final ExportFunction wasmMsgBoundedFlushAssign;
@@ -84,6 +85,8 @@ public WasmLocalResolver(Consumer<WriteFlagLogsRequest> logSink) {
     wasmMsgAlloc = instance.export("wasm_msg_alloc");
     wasmMsgFree = instance.export("wasm_msg_free");
     wasmMsgGuestSetResolverState = instance.export("wasm_msg_guest_set_resolver_state");
+    wasmMsgGuestSetEncryptedResolverState =
+        instance.export("wasm_msg_guest_set_encrypted_resolver_state");
     wasmMsgGuestRegisterResolve = instance.export("wasm_msg_guest_register_resolve");
     wasmMsgBoundedFlushLogs = instance.export("wasm_msg_guest_bounded_flush_logs");
     wasmMsgBoundedFlushAssign = instance.export("wasm_msg_guest_bounded_flush_assign");
@@ -131,6 +134,30 @@ public void setResolverState(byte[] state, String accountId, Sdk sdk) {
     }
   }
 
+  @Override
+  public void setEncryptedResolverState(byte[] encryptedState, byte[] encryptionKey, Sdk sdk) {
+    lock.lock();
+    try {
+      final var builder =
+          Messages.SetEncryptedResolverStateRequest.newBuilder()
+              .setEncryptedState(ByteString.copyFrom(encryptedState))
+              .setEncryptionKey(ByteString.copyFrom(encryptionKey));
+      if (sdk != null) {
+        builder.setSdk(sdk);
+      }
+      final byte[] request =
+          Messages.Request.newBuilder()
+              .setData(ByteString.copyFrom(builder.build().toByteArray()))
+              .build()
+              .toByteArray();
+      final int addr = transfer(request);
+      final int respPtr = (int) wasmMsgGuestSetEncryptedResolverState.apply(addr)[0];
+      consumeResponse(respPtr, Messages.Void::parseFrom);
+    } finally {
+      lock.unlock();
+    }
+  }
+
   @Override
   public CompletionStage<ResolveProcessResponse> resolveProcess(ResolveProcessRequest request) {
     lock.lock();