feat(auth): Add JSON object context support for Conditional Data Access

The ctx claim in bearer tokens and signed data tokens previously only
accepted a String, which meant structured CEL expressions like
request.context.role == 'admin' could not be satisfied. Add
setCtx(Map<String, Object>) overloads to BearerToken and
SignedDataTokens builders so the JWT ctx claim is serialized as a
nested JSON object. Also add setContext(Map) and getContextAsObject()
to Credentials for use with the high-level Skyflow client.

All changes are backwards compatible — existing setCtx(String) and
setContext(String) APIs are unchanged.

Refs SK-2679
Co-Authored-By: Claude <noreply@anthropic.com>

Author: samsternberg

README.md

@@ -2771,10 +2771,14 @@ public class BearerTokenGenerationExample {
 
 ## Generate bearer tokens with context
 
-**Context-aware authorization** embeds context values into a bearer token during its generation and so you can reference those values in your policies. This enables more flexible access controls, such as helping you track end-user identity when making API calls using service accounts, and facilitates using signed data tokens during detokenization. .
+**Context-aware authorization** embeds context values into a bearer token during its generation and so you can reference those values in your policies. This enables more flexible access controls, such as helping you track end-user identity when making API calls using service accounts, and facilitates using signed data tokens during detokenization.
 
 A service account with the `context_id` identifier generates bearer tokens containing context information, represented as a JWT claim in a Skyflow-generated bearer token. Tokens generated from such service accounts include a `context_identifier` claim, are valid for 60 minutes, and can be used to make API calls to the Data and Management APIs, depending on the service account's permissions.
 
+The context can be provided as a simple string or as a `Map<String, Object>` for structured context. Use a `Map` when your policies use Conditional Data Access with CEL expressions that reference nested context fields (e.g., `request.context.role == 'admin'`).
+
+### String context
+
 [Example](https://github.com/skyflowapi/skyflow-java/blob/main/samples/src/main/java/com/example/serviceaccount/BearerTokenGenerationWithContextExample.java):
 
 ```java
@@ -2783,60 +2787,44 @@ import com.skyflow.serviceaccount.util.BearerToken;
 
 import java.io.File;
 
-/**
- * Example program to generate a Bearer Token using Skyflow's BearerToken utility.
- * The token is generated using two approaches:
- * 1. By providing the credentials.json file path.
- * 2. By providing the contents of credentials.json as a string.
- */
-public class BearerTokenGenerationWithContextExample {
-    public static void main(String[] args) {
-        // Variable to store the generated Bearer Token
-        String bearerToken = null;
+// Generate Bearer Token with a simple string context
+String filePath = "<YOUR_CREDENTIALS_FILE_PATH>";
 
-        // Approach 1: Generate Bearer Token by specifying the path to the credentials.json file
-        try {
-            // Replace <YOUR_CREDENTIALS_FILE_PATH> with the full path to your credentials.json file
-            String filePath = "<YOUR_CREDENTIALS_FILE_PATH>";
+BearerToken token = BearerToken.builder()
+        .setCredentials(new File(filePath))
+        .setCtx("abc") // Simple string context
+        .build();
 
-            // Create a BearerToken object using the file path
-            BearerToken token = BearerToken.builder()
-                    .setCredentials(new File(filePath)) // Set credentials using a File object
-                    .setCtx("abc") // Set context string (example: "abc")
-                    .build(); // Build the BearerToken object
+String bearerToken = token.getBearerToken();
+```
 
-            // Retrieve the Bearer Token as a string
-            bearerToken = token.getBearerToken();
+### JSON object context (Conditional Data Access)
 
-            // Print the generated Bearer Token to the console
-            System.out.println(bearerToken);
-        } catch (SkyflowException e) {
-            // Handle exceptions specific to Skyflow operations
-            e.printStackTrace();
-        }
+Skyflow's [Conditional Data Access](https://docs.skyflow.com/docs/governance/roles/conditional-data-access/overview) feature enables dynamic, context-aware access control by allowing roles to activate only when specific conditions are met at runtime. Conditions are defined using Common Expression Language (CEL) expressions that evaluate against `request.context`, `request.time`, and `request.originIP`.
 
-        // Approach 2: Generate Bearer Token by specifying the contents of credentials.json as a string
-        try {
-            // Replace <YOUR_CREDENTIALS_FILE_CONTENTS_AS_STRING> with the actual contents of your credentials.json file
-            String fileContents = "<YOUR_CREDENTIALS_FILE_CONTENTS_AS_STRING>";
+To satisfy context-based conditions, pass a `Map<String, Object>` to `setCtx()`. The map is embedded as a nested JSON object in the JWT `ctx` claim, allowing CEL expressions to reference individual fields.
 
-            // Create a BearerToken object using the file contents as a string
-            BearerToken token = BearerToken.builder()
-                    .setCredentials(fileContents) // Set credentials using a string representation of the file
-                    .setCtx("abc") // Set context string (example: "abc")
-                    .build(); // Build the BearerToken object
+```java
+import com.skyflow.errors.SkyflowException;
+import com.skyflow.serviceaccount.util.BearerToken;
 
-            // Retrieve the Bearer Token as a string
-            bearerToken = token.getBearerToken();
+import java.io.File;
+import java.util.HashMap;
+import java.util.Map;
 
-            // Print the generated Bearer Token to the console
-            System.out.println(bearerToken);
-        } catch (SkyflowException e) {
-            // Handle exceptions specific to Skyflow operations
-            e.printStackTrace();
-        }
-    }
-}
+// Create a context map matching your Conditional Data Access policy
+// For example, if your policy condition is:
+//   request.context.role == 'admin' && request.context.project_id == 'proj_123'
+Map<String, Object> context = new HashMap<>();
+context.put("role", "admin");
+context.put("project_id", "proj_123");
+
+BearerToken token = BearerToken.builder()
+        .setCredentials(new File("<YOUR_CREDENTIALS_FILE_PATH>"))
+        .setCtx(context) // JSON object context for Conditional Data Access
+        .build();
+
+String bearerToken = token.getBearerToken();
 ```
 
 ## Generate scoped bearer tokens
@@ -2903,6 +2891,8 @@ with the private key of the service account credentials, which adds an additiona
 be detokenized by passing the signed data token and a bearer token generated from service account credentials. The
 service account must have appropriate permissions and context to detokenize the signed data tokens.
 
+Like bearer tokens, the context can be provided as a simple string or as a `Map<String, Object>` for Conditional Data Access.
+
 [Example](https://github.com/skyflowapi/skyflow-java/blob/main/samples/src/main/java/com/example/serviceaccount/SignedTokenGenerationExample.java):
 
 ```java
@@ -2912,12 +2902,15 @@ import com.skyflow.serviceaccount.util.SignedDataTokens;
 
 import java.io.File;
 import java.util.ArrayList;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 
 public class SignedTokenGenerationExample {
     public static void main(String[] args) {
         List<SignedDataTokenResponse> signedTokenValues;
-        // Generate Signed data token with context by specifying credentials.json file path
+
+        // Generate Signed data token with string context
         try {
             String filePath = "<YOUR_CREDENTIALS_FILE_PATH>";
             String context = "abc";
@@ -2935,15 +2928,17 @@ public class SignedTokenGenerationExample {
             e.printStackTrace();
         }
 
-        // Generate Signed data token with context by specifying credentials.json as string
+        // Generate Signed data token with JSON object context for Conditional Data Access
         try {
-            String fileContents = "<YOUR_CREDENTIALS_FILE_CONTENTS_AS_STRING>";
-            String context = "abc";
+            String filePath = "<YOUR_CREDENTIALS_FILE_PATH>";
+            Map<String, Object> context = new HashMap<>();
+            context.put("role", "admin");
+            context.put("project_id", "proj_123");
             ArrayList<String> dataTokens = new ArrayList<>();
             dataTokens.add("YOUR_DATA_TOKEN_1");
             SignedDataTokens signedToken = SignedDataTokens.builder()
-                    .setCredentials(fileContents)
-                    .setCtx(context)
+                    .setCredentials(new File(filePath))
+                    .setCtx(context) // JSON object context
                     .setTimeToLive(30) // in seconds
                     .setDataTokens(dataTokens)
                     .build();

samples/src/main/java/com/example/serviceaccount/BearerTokenGenerationWithContextExample.java

@@ -4,12 +4,15 @@
 import com.skyflow.serviceaccount.util.BearerToken;
 
 import java.io.File;
+import java.util.HashMap;
+import java.util.Map;
 
 /**
  * Example program to generate a Bearer Token using Skyflow's BearerToken utility.
- * The token is generated using two approaches:
- * 1. By providing the credentials.json file path.
- * 2. By providing the contents of credentials.json as a string.
+ * The token is generated using three approaches:
+ * 1. By providing the credentials.json file path with a string context.
+ * 2. By providing the contents of credentials.json as a string with a string context.
+ * 3. By providing a JSON object context for Conditional Data Access.
  */
 public class BearerTokenGenerationWithContextExample {
     public static void main(String[] args) {
@@ -57,5 +60,33 @@ public static void main(String[] args) {
             // Handle exceptions specific to Skyflow operations
             e.printStackTrace();
         }
+
+        // Approach 3: Generate Bearer Token with a JSON object context for Conditional Data Access
+        // Use this approach when your Skyflow policy uses CEL expressions that reference nested
+        // context fields, such as: request.context.role == 'admin'
+        try {
+            // Replace <YOUR_CREDENTIALS_FILE_PATH> with the full path to your credentials.json file
+            String filePath = "<YOUR_CREDENTIALS_FILE_PATH>";
+
+            // Create a context map with key-value pairs matching your Conditional Data Access policy
+            Map<String, Object> context = new HashMap<>();
+            context.put("role", "admin");              // Evaluated as request.context.role
+            context.put("project_id", "proj_123");     // Evaluated as request.context.project_id
+
+            // Create a BearerToken object with the JSON object context
+            BearerToken token = BearerToken.builder()
+                    .setCredentials(new File(filePath)) // Set credentials using a File object
+                    .setCtx(context)                    // Set context as a JSON object
+                    .build();                           // Build the BearerToken object
+
+            // Retrieve the Bearer Token as a string
+            bearerToken = token.getBearerToken();
+
+            // Print the generated Bearer Token to the console
+            System.out.println(bearerToken);
+        } catch (SkyflowException e) {
+            // Handle exceptions specific to Skyflow operations
+            e.printStackTrace();
+        }
     }
 }

samples/src/main/java/com/example/serviceaccount/SignedTokenGenerationExample.java

@@ -6,12 +6,15 @@
 
 import java.io.File;
 import java.util.ArrayList;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 
 /**
- * This example demonstrates how to generate Signed Data Tokens using two methods:
- * 1. Specifying the path to a credentials JSON file.
- * 2. Providing the credentials JSON as a string.
+ * This example demonstrates how to generate Signed Data Tokens using three methods:
+ * 1. Specifying the path to a credentials JSON file with a string context.
+ * 2. Providing the credentials JSON as a string with a string context.
+ * 3. Using a JSON object context for Conditional Data Access.
  * <p>
  * Signed data tokens are used to verify and securely transmit data with a specified context and TTL.
  */
@@ -70,5 +73,36 @@ public static void main(String[] args) {
             System.out.println("Error occurred while generating signed tokens using credentials string:");
             e.printStackTrace();
         }
+
+        // Example 3: Generate Signed Data Token with a JSON object context for Conditional Data Access
+        // Use this approach when your Skyflow policy uses CEL expressions that reference nested
+        // context fields, such as: request.context.role == 'admin'
+        try {
+            // Step 1: Specify the path to the service account credentials JSON file
+            String filePath = "<YOUR_CREDENTIALS_FILE_PATH>"; // Replace with the actual file path
+
+            // Step 2: Create a context map with key-value pairs matching your Conditional Data Access policy
+            Map<String, Object> context = new HashMap<>();
+            context.put("role", "admin");              // Evaluated as request.context.role
+            context.put("project_id", "proj_123");     // Evaluated as request.context.project_id
+
+            ArrayList<String> dataTokens = new ArrayList<>();
+            dataTokens.add("YOUR_DATA_TOKEN_1"); // Replace with your actual data token(s)
+
+            // Step 3: Build the SignedDataTokens object with the JSON object context
+            SignedDataTokens signedToken = SignedDataTokens.builder()
+                    .setCredentials(new File(filePath)) // Provide the credentials file
+                    .setCtx(context)                    // Set context as a JSON object
+                    .setTimeToLive(30)                  // Set the TTL (in seconds)
+                    .setDataTokens(dataTokens)          // Set the data tokens to sign
+                    .build();
+
+            // Step 4: Retrieve and print the signed data tokens
+            signedTokenValues = signedToken.getSignedDataTokens();
+            System.out.println("Signed Tokens (using JSON object context): " + signedTokenValues);
+        } catch (SkyflowException e) {
+            System.out.println("Error occurred while generating signed tokens with JSON object context:");
+            e.printStackTrace();
+        }
     }
 }

src/main/java/com/skyflow/config/Credentials.java

@@ -1,11 +1,12 @@
 package com.skyflow.config;
 
 import java.util.ArrayList;
+import java.util.Map;
 
 public class Credentials {
     private String path;
     private ArrayList<String> roles;
-    private String context;
+    private Object context;
     private String credentialsString;
     private String token;
     private String apiKey;
@@ -33,13 +34,21 @@ public void setRoles(ArrayList<String> roles) {
     }
 
     public String getContext() {
+        return context instanceof String ? (String) context : null;
+    }
+
+    public Object getContextAsObject() {
         return context;
     }
 
     public void setContext(String context) {
         this.context = context;
     }
 
+    public void setContext(Map<String, Object> context) {
+        this.context = context;
+    }
+
     public String getCredentialsString() {
         return credentialsString;
     }

src/main/java/com/skyflow/errors/ErrorMessage.java

@@ -34,6 +34,8 @@ public enum ErrorMessage {
     EmptyRoles("%s0 Initialization failed. Invalid roles. Specify at least one role."),
     EmptyRoleInRoles("%s0 Initialization failed. Invalid role. Specify a valid role."),
     EmptyContext("%s0 Initialization failed. Invalid context. Specify a valid context."),
+    InvalidCtxType("%s0 Initialization failed. Invalid context type. Context must be a string or a map."),
+    InvalidCtxMapKey("%s0 Initialization failed. Invalid context map key '%s1'. Context map keys must contain only alphanumeric characters and underscores."),
 
     // Bearer token generation
     FileNotFound("%s0 Initialization failed. Credential file not found at %s1. Verify the file path."),

src/main/java/com/skyflow/logs/ErrorLogs.java

@@ -25,6 +25,8 @@ public enum ErrorLogs {
     EMPTY_ROLES("Invalid credentials. Roles can not be empty."),
     EMPTY_OR_NULL_ROLE_IN_ROLES("Invalid credentials. Role can not be null or empty in roles at index %s1."),
     EMPTY_OR_NULL_CONTEXT("Invalid credentials. Context can not be empty."),
+    INVALID_CTX_TYPE("Invalid credentials. Context must be a string or a map."),
+    INVALID_CTX_MAP_KEY("Invalid credentials. Context map key '%s1' is invalid. Keys must match ^[a-zA-Z0-9_]+$."),
 
     // Bearer token generation
     INVALID_BEARER_TOKEN("Bearer token is invalid or expired."),