feat(sdk): DSPX-2418 add attribute discovery methods by marythought · Pull Request #841 · opentdf/web-sdk

marythought · 2026-02-17T23:51:13Z

Summary

Add five discovery methods in lib/src/policy/discovery.ts, exported from the package root:
- listAttributes(),
- validateAttributes(),
- attributeExists(),
- attributeValueExists(),
- getEntityAttributes() -- REMOVED (not applicable)
Add AttributeNotFoundError extends TdfError, exported from the package root so callers can
distinguish "not found" from other errors
Add unit tests in discovery.spec.ts covering all methods and edge cases
docs update: Feat: DSPX-2418 add SDK convenience/discovery method documentation docs#186

Rationale

Addresses GitHub discussion developer feedback. These methods provide ergonomic wrappers over the
lower-level PlatformClient 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 createZTDF() 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-side limit
Restrict FQN strings to safe URL characters to prevent XSS via FQNs in error messages

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

Test plan

npm test in lib/ — all tests pass, no regressions

gemini-code-assist · 2026-02-17T23:51:30Z

Summary of Changes

Hello @marythought, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the SDK's capabilities for interacting with the platform's attribute system. It introduces a suite of new functions designed to simplify the process of discovering available attributes, validating attribute FQNs against the platform, and retrieving attributes associated with specific entities. These additions aim to improve developer experience by providing robust tools for attribute management and early detection of configuration issues, thereby streamlining the development of applications that rely on attribute-based access control.

Highlights

New Attribute Discovery Methods: Four convenience methods have been added for attribute discovery and validation: listAttributes, validateAttributes, validateAttributeValue, and getEntityAttributes.
listAttributes: This method auto-paginates through all active attributes on the platform, with an optional namespace filter.
validateAttributes and validateAttributeValue: These methods validate the format of Fully Qualified Names (FQNs) and confirm their existence on the platform, throwing an AttributeNotFoundError for any missing FQNs. validateAttributeValue is a single-FQN wrapper.
getEntityAttributes: This method returns the attribute value FQNs assigned to a Policy Enforcement (PE) or Non-Policy Enforcement (NPE) entity by leveraging GetEntitlements.
AttributeNotFoundError: A new error type, AttributeNotFoundError, has been introduced, extending TdfError, to specifically indicate when attribute value FQNs are not found on the platform.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

lib/src/errors.ts
- Added AttributeNotFoundError class for specific attribute not found scenarios.
lib/src/index.ts
- Exported new attribute discovery and validation functions (listAttributes, validateAttributes, validateAttributeValue, getEntityAttributes).
- Exported AttributeNotFoundError for public API access.
lib/src/policy/discovery.ts
- Implemented listAttributes for paginated retrieval of active attributes.
- Implemented validateAttributes to check FQN format and existence on the platform.
- Implemented validateAttributeValue as a convenience wrapper for single FQN validation.
- Implemented getEntityAttributes to fetch attribute FQNs assigned to an entity.
- Defined constants for pagination limits and FQN validation regex.
lib/tests/mocha/unit/discovery.spec.ts
- Added unit tests for validateAttributes covering null/empty input, FQN count limits, and invalid FQN formats.
- Added unit tests for validateAttributeValue to verify invalid FQN format handling.
- Added unit tests for getEntityAttributes to ensure proper handling of null/undefined entity input.
- Included a test to confirm AttributeNotFoundError correctly extends Error.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces several useful convenience methods for attribute discovery and validation, along with a new AttributeNotFoundError. While the implementation is generally well-structured, there are critical security concerns regarding the handling of user-supplied URLs and FQNs, which could lead to reflected Cross-Site Scripting (XSS) and potential credential theft if not properly addressed. Additionally, I've provided a couple of suggestions to improve code clarity and conciseness in the new discovery.ts file.

Add four convenience methods for attribute discovery and validation: - listAttributes(platformUrl, authProvider, namespace?) — auto-paginates through all active attributes; optional namespace filter - validateAttributes(platformUrl, authProvider, fqns[]) — validates FQN format then confirms existence on the platform; throws AttributeNotFoundError for missing FQNs; capped at 250 FQNs to match the server limit - validateAttributeValue(platformUrl, authProvider, fqn) — single-FQN convenience wrapper around validateAttributes - getEntityAttributes(platformUrl, authProvider, entity) — returns the attribute value FQNs assigned to a PE or NPE via GetEntitlements Also adds AttributeNotFoundError (extends TdfError) exported from the package root for callers to distinguish "not found" from other errors. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Mary Dickson <mary.dickson@virtru.com>

github-actions · 2026-02-18T00:05:59Z

X-Test Failure Report

opentdf-sdk-lib
opentdf-ctl
✅ go-v0.9.0

github-actions · 2026-02-18T00:35:28Z

X-Test Results

opentdf-sdk-lib
opentdf-ctl
✅ go-v0.9.0
✅ go-main
✅ java-v0.9.0
✅ java-main
✅ js-v0.9.0
✅ js-main

…dd new validateAttributeValue The old validateAttributeValue(fqn) only checked if a complete value FQN was pre-registered on the platform. This gave false negatives for dynamic (non-enumerated) attributes where any string value is valid. - Rename validateAttributeValue(fqn) → validateAttributeExists(fqn). - Add validateAttributeValue(platformUrl, authProvider, attributeFqn, value) which fetches the attribute definition via getAttribute: - Enumerated attribute (values non-empty): value must match case-insensitively. - Dynamic attribute (values empty): any string is accepted. - Add ATTRIBUTE_FQN_RE regex for attribute-level FQN validation. - Export validateAttributeExists from index.ts. - Add 2 new input-validation tests; rename existing validateAttributeValue describe block to validateAttributeExists. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-02-18T00:53:58Z

If these changes look good, signoff on them with:

git pull && git commit --amend --signoff && git push --force-with-lease origin

If they aren't any good, please remove them with:

git pull && git reset --hard HEAD~1 && git push --force-with-lease origin

Signed-off-by: Mary Dickson <mary.dickson@virtru.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-02-18T01:34:14Z

X-Test Results

opentdf-sdk-lib
opentdf-ctl
✅ go-main
✅ go-v0.9.0
✅ java-v0.9.0
✅ java-main
✅ js-v0.9.0
✅ js-main

- Remove getEntityAttributes: GetEntitlements is server-side/PEP only; in browser contexts there is no way to distinguish PEP auth from user auth, risking entitlement mining of other users - Set explicit LIST_ATTRIBUTES_PAGE_SIZE=1000 (matches platform default) so listAttributes behavior is stable regardless of server config changes - Reduce MAX_LIST_ATTRIBUTES_PAGES from 1000 to 10 (10k record cap is generous for browser use) - Improve page-limit error message to explain the cause and suggest the namespace filter - Clarify MAX_VALIDATE_FQNS=250 comment: traces to max_items:250 in the GetAttributeValuesByFqnsRequest proto constraint - Include value and attributeFqn in validateAttributeValue error message Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-02-19T16:28:30Z

If these changes look good, signoff on them with:

git pull && git commit --amend --signoff && git push --force-with-lease origin

If they aren't any good, please remove them with:

git pull && git reset --hard HEAD~1 && git push --force-with-lease origin

Signed-off-by: Mary Dickson <mary.dickson@virtru.com>

eugenioenko

Code changes look good, the addition of tests also helps.

Nicely done!

eugenioenko · 2026-02-19T16:49:48Z

One thing I'm noticing and it's already an established pattern, when we need isolated functions to call endpoints we end up instantiating a new PlatformClient. Ex:

asycn funtion Foo() {
   const client = new PlatformClient({...});
   const response = await client.v1.policy.call({});

Instantiating a new client each time is more expensive, Connect RPC recommends avoiding creating new transport each time, here some reference:
https://connectrpc.com/docs/web/using-clients/#managing-clients-and-transports

This is not something we need to fix in this PR, but I feel like we need to give it some thought and it might affect some of our interfaces, so that's something to keep in mind

github-actions · 2026-02-19T17:03:33Z

X-Test Results

opentdf-sdk-lib
opentdf-ctl
✅ go-main
✅ go-v0.9.0
✅ java-v0.9.0
✅ java-main
✅ js-v0.9.0
✅ js-main

An attribute with no registered values now throws AttributeNotFoundError instead of silently succeeding. Also aligns error messages with Go and Java SDKs, and includes the FQN in the attribute-not-found error. Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-02-19T18:01:16Z

X-Test Results

opentdf-sdk-lib
opentdf-ctl
✅ go-main
✅ go-v0.9.0
✅ java-main
✅ java-v0.9.0
✅ js-v0.9.0
✅ js-main

…eValue with attributeExists/attributeValueExists Both methods now return bool instead of throwing on not-found, aligning with idiomatic TypeScript conventions for existence checks. ConnectError with Code.NotFound is caught and mapped to false; other errors propagate as NetworkError. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-02-19T19:33:24Z

X-Test Results

opentdf-sdk-lib
opentdf-ctl
✅ go-main
✅ go-v0.9.0
✅ java-main
✅ java-v0.9.0
✅ js-v0.9.0
✅ js-main

marythought requested a review from a team as a code owner February 17, 2026 23:51

gemini-code-assist Bot reviewed Feb 17, 2026

View reviewed changes

Comment thread lib/src/policy/discovery.ts

Comment thread lib/src/policy/discovery.ts

Comment thread lib/src/policy/discovery.ts Outdated

Comment thread lib/src/policy/discovery.ts Outdated

marythought force-pushed the feat/dspx-2418-discovery-methods branch from c9abaa5 to 08b8f54 Compare February 18, 2026 00:02

marythought and others added 2 commits February 17, 2026 16:37

feat(sdk): add empty value guard to validateAttributeValue

56d1476

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

🤖 🎨 Autoformat

580b0f8

Signed-off-by: Mary Dickson <mary.dickson@virtru.com>

marythought force-pushed the feat/dspx-2418-discovery-methods branch from 73e7966 to 580b0f8 Compare February 18, 2026 00:58

fix(sdk): drop unused catch binding to satisfy no-unused-vars lint rule

46ae054

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

jakedoublev reviewed Feb 18, 2026

View reviewed changes

Comment thread lib/src/policy/discovery.ts Outdated

eugenioenko reviewed Feb 18, 2026

View reviewed changes

Comment thread lib/src/policy/discovery.ts Outdated

eugenioenko reviewed Feb 18, 2026

View reviewed changes

Comment thread lib/src/policy/discovery.ts

eugenioenko reviewed Feb 18, 2026

View reviewed changes

Comment thread lib/src/policy/discovery.ts Outdated

marythought requested review from eugenioenko and jakedoublev February 19, 2026 16:27

🤖 🎨 Autoformat

e8b66cd

Signed-off-by: Mary Dickson <mary.dickson@virtru.com>

marythought force-pushed the feat/dspx-2418-discovery-methods branch from fc30fdf to e8b66cd Compare February 19, 2026 16:29

eugenioenko previously approved these changes Feb 19, 2026

View reviewed changes

marythought dismissed eugenioenko’s stale review via 392f676 February 19, 2026 17:28

eugenioenko approved these changes Feb 19, 2026

View reviewed changes

marythought merged commit 06c5964 into main Feb 19, 2026
22 checks passed

marythought deleted the feat/dspx-2418-discovery-methods branch February 19, 2026 21:53

opentdf-automation Bot mentioned this pull request Feb 19, 2026

chore(sdk): release sdk 0.10.0 #838

Merged

Uh oh!

Conversation

marythought commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Rationale

Test plan

Uh oh!

gemini-code-assist Bot commented Feb 17, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Feb 18, 2026

X-Test Failure Report

Uh oh!

github-actions Bot commented Feb 18, 2026

X-Test Results

Uh oh!

github-actions Bot commented Feb 18, 2026

Uh oh!

github-actions Bot commented Feb 18, 2026

X-Test Results

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Feb 19, 2026

Uh oh!

eugenioenko left a comment

Choose a reason for hiding this comment

Uh oh!

eugenioenko commented Feb 19, 2026

Uh oh!

github-actions Bot commented Feb 19, 2026

X-Test Results

Uh oh!

github-actions Bot commented Feb 19, 2026

X-Test Results

Uh oh!

github-actions Bot commented Feb 19, 2026

X-Test Results

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

marythought commented Feb 17, 2026 •

edited

Loading