feat(sdk): DSPX-2418 add discovery convenience methods (#339)

## Summary

- Add five discovery methods directly on the `SDK` class:
`listAttributes()`,
  `validateAttributes()`, `attributeExists()`, `attributeValueExists()`,
  `getEntityAttributes()`
- Add `SDK.AttributeNotFoundException extends SDKException`, thrown when
FQNs or attribute
  values are not found on the platform
- Add 26 unit tests in `DiscoveryTest.java` covering all methods and
edge cases
- docs update: opentdf/docs#186

## Rationale

Addresses GitHub discussion developer feedback. Developers currently
work with verbose Connect RPC
request/response types through `sdk.getServices().attributes()`. These
methods provide ergonomic
wrappers that:

- Auto-paginate `listAttributes()` with a 1,000-page safety cap to
prevent unbounded memory
  growth from a misbehaving server
- Validate FQN format and existence before `createTDF()` so failures
happen at encryption time
with a clear message rather than at decryption time with a cryptic
"resource not found"
- Match entity ID in the `GetEntitlements` response to prevent silent
wrong-entity attribute
  returns
- Cap `validateAttributes()` at 250 FQNs client-side to match the server
limit

Matches the API shape and security properties of the Go SDK
implementation: opentdf/platform#3082.

## Test plan

- [ ] `mvn -pl sdk test -Dtest=DiscoveryTest` — all 26 tests pass
- [ ] `mvn -pl sdk test` — no regressions in existing test suite

---------

Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: marythought

sdk/src/main/java/io/opentdf/platform/sdk/SDK.java

@@ -1,11 +1,22 @@
 package io.opentdf.platform.sdk;
 
 import com.connectrpc.Interceptor;
-
+import com.connectrpc.ResponseMessageKt;
 import com.connectrpc.impl.ProtocolClient;
 import io.opentdf.platform.authorization.AuthorizationServiceClientInterface;
+import io.opentdf.platform.authorization.Entity;
+import io.opentdf.platform.authorization.EntityEntitlements;
+import io.opentdf.platform.authorization.GetEntitlementsRequest;
+import io.opentdf.platform.authorization.GetEntitlementsResponse;
+import io.opentdf.platform.policy.Attribute;
+import io.opentdf.platform.policy.PageRequest;
 import io.opentdf.platform.policy.SimpleKasKey;
+import io.opentdf.platform.policy.Value;
 import io.opentdf.platform.policy.attributes.AttributesServiceClientInterface;
+import io.opentdf.platform.policy.attributes.GetAttributeRequest;
+import io.opentdf.platform.policy.attributes.GetAttributeValuesByFqnsRequest;
+import io.opentdf.platform.policy.attributes.GetAttributeValuesByFqnsResponse;
+import io.opentdf.platform.policy.attributes.ListAttributesRequest;
 import io.opentdf.platform.policy.kasregistry.KeyAccessServerRegistryServiceClientInterface;
 import io.opentdf.platform.policy.namespaces.NamespaceServiceClientInterface;
 import io.opentdf.platform.policy.resourcemapping.ResourceMappingServiceClientInterface;
@@ -17,7 +28,12 @@
 import java.io.InputStream;
 import java.io.OutputStream;
 import java.nio.channels.SeekableByteChannel;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
 import java.util.Optional;
+import java.util.stream.Collectors;
 
 /**
  * The SDK class represents a software development kit for interacting with the
@@ -26,6 +42,15 @@
  * platform.
  */
 public class SDK implements AutoCloseable {
+
+    // Caps the pagination loop in listAttributes to prevent unbounded memory growth
+    // if a server repeatedly returns a non-zero next_offset.
+    private static final int MAX_LIST_ATTRIBUTES_PAGES = 1000;
+
+    // Matches the server-side limit on GetAttributeValuesByFqns so callers get a
+    // clear local error instead of a cryptic server rejection.
+    private static final int MAX_VALIDATE_FQNS = 250;
+
     private final Services services;
     private final TrustManager trustManager;
     private final Interceptor authInterceptor;
@@ -179,6 +204,172 @@ public String getPlatformUrl() {
         return platformUrl;
     }
 
+    /**
+     * Lists all active attributes available on the platform, auto-paginating through all results.
+     * An optional namespace name or ID may be provided to filter results.
+     *
+     * <p>Use this before calling {@code createTDF()} to see what attributes are available for data tagging.
+     *
+     * @param namespace optional namespace name or ID to filter results
+     * @return list of all active {@link Attribute} objects
+     * @throws SDKException if a service error occurs or pagination exceeds the maximum page limit
+     */
+    public List<Attribute> listAttributes(String... namespace) {
+        ListAttributesRequest.Builder reqBuilder = ListAttributesRequest.newBuilder();
+        if (namespace.length > 0 && namespace[0] != null) {
+            reqBuilder.setNamespace(namespace[0]);
+        }
+        List<Attribute> result = new ArrayList<>();
+        for (int pages = 0; pages < MAX_LIST_ATTRIBUTES_PAGES; pages++) {
+            var resp = ResponseMessageKt.getOrThrow(
+                    services.attributes()
+                            .listAttributesBlocking(reqBuilder.build(), Collections.emptyMap())
+                            .execute());
+            result.addAll(resp.getAttributesList());
+            int nextOffset = resp.getPagination().getNextOffset();
+            if (nextOffset == 0) {
+                return result;
+            }
+            reqBuilder.setPagination(PageRequest.newBuilder().setOffset(nextOffset).build());
+        }
+        throw new SDKException("listing attributes: exceeded maximum page limit (" + MAX_LIST_ATTRIBUTES_PAGES + ")");
+    }
+
+    /**
+     * Checks that all provided attribute value FQNs exist on the platform.
+     * Validates FQN format first, then verifies existence via the platform API.
+     *
+     * <p>Use this before {@code createTDF()} to catch missing or misspelled attributes early
+     * instead of discovering the problem at decryption time.
+     *
+     * @param fqns list of attribute value FQNs in the form
+     *             {@code https://<namespace>/attr/<name>/value/<value>}
+     * @throws AttributeNotFoundException if any FQNs are not found on the platform
+     * @throws SDKException if input validation fails or a service error occurs
+     */
+    public void validateAttributes(List<String> fqns) {
+        if (fqns == null || fqns.isEmpty()) {
+            return;
+        }
+        if (fqns.size() > MAX_VALIDATE_FQNS) {
+            throw new SDKException("too many attribute FQNs: " + fqns.size()
+                    + " exceeds maximum of " + MAX_VALIDATE_FQNS);
+        }
+        for (String fqn : fqns) {
+            try {
+                new Autoconfigure.AttributeValueFQN(fqn);
+            } catch (AutoConfigureException e) {
+                throw new SDKException("invalid attribute value FQN \"" + fqn + "\": " + e.getMessage(), e);
+            }
+        }
+        GetAttributeValuesByFqnsResponse resp = ResponseMessageKt.getOrThrow(
+                services.attributes()
+                        .getAttributeValuesByFqnsBlocking(
+                                GetAttributeValuesByFqnsRequest.newBuilder().addAllFqns(fqns).build(),
+                                Collections.emptyMap())
+                        .execute());
+        Map<String, GetAttributeValuesByFqnsResponse.AttributeAndValue> found = resp.getFqnAttributeValuesMap();
+        List<String> missing = fqns.stream()
+                .filter(f -> !found.containsKey(f))
+                .collect(Collectors.toList());
+        if (!missing.isEmpty()) {
+            throw new AttributeNotFoundException("attribute not found: " + String.join(", ", missing));
+        }
+    }
+
+    /**
+     * Returns the attribute value FQNs assigned to an entity (person or non-person entity).
+     *
+     * <p>Use this to inspect what attributes a user, service account, or other entity has been
+     * granted before making authorization decisions or constructing access policies.
+     *
+     * @param entity the entity to look up; must not be null
+     * @return list of attribute value FQNs assigned to the entity, or an empty list if none
+     * @throws SDKException if entity is null or a service error occurs
+     */
+    public List<String> getEntityAttributes(Entity entity) {
+        if (entity == null) {
+            throw new SDKException("entity must not be null");
+        }
+        GetEntitlementsResponse resp = ResponseMessageKt.getOrThrow(
+                services.authorization()
+                        .getEntitlementsBlocking(
+                                GetEntitlementsRequest.newBuilder().addEntities(entity).build(),
+                                Collections.emptyMap())
+                        .execute());
+        String entityId = entity.getId();
+        for (EntityEntitlements e : resp.getEntitlementsList()) {
+            if (e.getEntityId().equals(entityId)) {
+                return e.getAttributeValueFqnsList();
+            }
+        }
+        return Collections.emptyList();
+    }
+
+    /**
+     * Reports whether the attribute definition identified by {@code attributeFqn} exists on the
+     * platform.
+     *
+     * <p>{@code attributeFqn} should be an attribute-level FQN (no {@code /value/} segment):
+     * <pre>{@code https://<namespace>/attr/<attribute_name>}</pre>
+     *
+     * @param attributeFqn the attribute-level FQN to check
+     * @return {@code true} if the attribute exists, {@code false} if it does not
+     * @throws SDKException if the FQN format is invalid or a non-not-found service error occurs
+     */
+    public boolean attributeExists(String attributeFqn) {
+        try {
+            new Autoconfigure.AttributeNameFQN(attributeFqn);
+        } catch (AutoConfigureException e) {
+            throw new SDKException("invalid attribute FQN \"" + attributeFqn + "\": " + e.getMessage(), e);
+        }
+        try {
+            ResponseMessageKt.getOrThrow(
+                    services.attributes()
+                            .getAttributeBlocking(
+                                    GetAttributeRequest.newBuilder().setFqn(attributeFqn).build(),
+                                    Collections.emptyMap())
+                            .execute());
+            return true;
+        } catch (Exception e) {
+            String msg = e.getMessage();
+            if (msg != null && msg.contains("not_found")) {
+                return false;
+            }
+            throw new SDKException("checking attribute existence: " + msg, e);
+        }
+    }
+
+    /**
+     * Reports whether the attribute value FQN exists on the platform.
+     *
+     * <p>{@code valueFqn} should be a full attribute value FQN (with {@code /value/} segment):
+     * <pre>{@code https://<namespace>/attr/<attribute_name>/value/<value>}</pre>
+     *
+     * @param valueFqn the attribute value FQN to check
+     * @return {@code true} if the value exists, {@code false} if it does not
+     * @throws SDKException if the FQN format is invalid or a service error occurs
+     */
+    public boolean attributeValueExists(String valueFqn) {
+        try {
+            new Autoconfigure.AttributeValueFQN(valueFqn);
+        } catch (AutoConfigureException e) {
+            throw new SDKException("invalid attribute value FQN \"" + valueFqn + "\": " + e.getMessage(), e);
+        }
+        GetAttributeValuesByFqnsResponse resp;
+        try {
+            resp = ResponseMessageKt.getOrThrow(
+                    services.attributes()
+                            .getAttributeValuesByFqnsBlocking(
+                                    GetAttributeValuesByFqnsRequest.newBuilder().addFqns(valueFqn).build(),
+                                    Collections.emptyMap())
+                            .execute());
+        } catch (Exception e) {
+            throw new SDKException("checking attribute value existence: " + e.getMessage(), e);
+        }
+        return resp.getFqnAttributeValuesMap().containsKey(valueFqn);
+    }
+
     /**
      *  Indicates that the TDF is malformed in some way
      */
@@ -284,4 +475,16 @@ public AssertionException(String errorMessage, String id) {
             super("assertion id: "+ id + "; " + errorMessage);
         }
     }
+
+    /**
+     * {@link AttributeNotFoundException} is thrown by {@link #validateAttributes(List)},
+     * {@link #validateAttributeExists(String)}, and
+     * {@link #validateAttributeValue(String, String)} when one or more attributes or values
+     * are not found on the platform.
+     */
+    public static class AttributeNotFoundException extends SDKException {
+        public AttributeNotFoundException(String errorMessage) {
+            super(errorMessage);
+        }
+    }
 }