feat(sdk): ergonomic EntityIdentifier constructors for authorization v2

[marythought]

Summary

• Adds five convenience constructors (EntityIdentifierForToken, EntityIdentifierWithRequestToken, EntityIdentifierForClientID, EntityIdentifierForEmail, EntityIdentifierForUserName) in the sdk package that return a ready-to-use *authorizationv2.EntityIdentifier
• Eliminates the 4-level proto nesting previously required for common entity identification cases in v2 authorization requests
• Lives in the sdk package so no extra import is needed for existing SDK consumers
• Includes table-driven unit tests with edge cases for all constructors

These helpers work with all four v2 authorization methods:

• GetDecision — single resource authorization check
• GetDecisionMultiResource — check one entity against multiple resources
• GetDecisionBulk — batch of full decision requests
• GetEntitlements — retrieve attribute entitlements for an entity

Example

Before:

req := &authorizationv2.GetDecisionRequest{
    EntityIdentifier: &authorizationv2.EntityIdentifier{
        Identifier: &authorizationv2.EntityIdentifier_EntityChain{
            EntityChain: &entity.EntityChain{
                Entities: []*entity.Entity{{
                    EntityType: &entity.Entity_ClientId{ClientId: "opentdf"},
                }},
            },
        },
    },
    // ...
}

After:

req := &authorizationv2.GetDecisionRequest{
    EntityIdentifier: sdk.EntityIdentifierForClientID("opentdf"),
    // ...
}

Test plan

• go test ./sdk/... -run TestEntityIdentifier — all tests pass
• go test ./sdk/... -run TestEntityChain — table-driven tests pass
• golangci-lint run sdk/entity_identifier.go sdk/entity_identifier_test.go — 0 issues

🤖 Generated with Claude Code

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Added a new Go source file implementing five exported EntityIdentifier constructors (token, request token, client ID, email, username) and a private helper, plus a test file with unit tests validating each constructor's return type and stored values.

Changes

Cohort / File(s)	Summary
EntityIdentifier constructors & tests protocol/go/authorization/v2/entity_identifier.go, protocol/go/authorization/v2/entity_identifier_test.go	Introduced exported constructors: ForToken, WithRequestToken, ForClientID, ForEmail, ForUserName, and an unexported entityIdentifierFromEntity helper; added tests covering token/request-token cases and single-entity chains verifying category, type, and stored values (including empty-string cases).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I nibble tokens, names, and IDs with glee,
I bind each chain so resolvers can see,
A request-flag hop, a helper tucked tight,
Tests lined up in a neat little row tonight,
Hooray for identifiers — swift and spry!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 43.48% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding ergonomic constructor functions for EntityIdentifier in the authorization v2 module.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch DSPX-2594-entity-identifier-helpers

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Summary of Changes

Hello, 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 introduces a set of ergonomic constructor functions within the SDK to streamline the instantiation of authorization entity identifiers. By abstracting the underlying protocol buffer structure, these changes make the developer experience more intuitive and reduce the verbosity required for common authorization tasks.

Highlights

• Convenience Constructors: Added five new helper functions (ForToken, WithRequestToken, ForClientID, ForEmail, ForUserName) to simplify the creation of EntityIdentifier objects.
• Reduced Boilerplate: Significantly reduced the complexity of authorization requests by eliminating the need for deep proto nesting when defining entity identifiers.
• Testing: Included comprehensive unit tests for all new constructors to ensure correct protocol buffer structure generation.

🧠 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.

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.

---

With builders clean and code so bright, / The nested structs now take to flight. / No more deep chains to make us weep, / Just simple calls for us to keep.

Footnotes

1. 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]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	189.101595ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	93.984904ms

Benchmark Statistics

Name	№ Requests	Avg Duration	Min Duration	Max Duration

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	383.151481ms
Throughput	260.99 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	39.778792206s
Average Latency	395.79023ms
Throughput	125.70 requests/second

[github-actions]

X-Test Results

✅ go-pull-3232
✅ go-v0.9.0
✅ java-pull-3232
✅ js-pull-3232
✅ java-v0.9.0
✅ js-v0.9.0
test-cases-mapping-report
bats-test-results
cukes-report
opentdfplatformJF2PK6.dockerbuild

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	183.510297ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	89.736877ms

Benchmark Statistics

Name	№ Requests	Avg Duration	Min Duration	Max Duration

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	409.024782ms
Throughput	244.48 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	40.392944017s
Average Latency	402.245808ms
Throughput	123.78 requests/second

[github-actions]

X-Test Results

✅ go-pull-3232
✅ go-v0.9.0
✅ java-pull-3232
✅ java-v0.9.0
✅ js-pull-3232
✅ js-v0.9.0
test-cases-mapping-report
bats-test-results
cukes-report
opentdfplatform6QOC6Y.dockerbuild

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	202.230264ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	100.49553ms

Benchmark Statistics

Name	№ Requests	Avg Duration	Min Duration	Max Duration

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	383.932203ms
Throughput	260.46 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	39.983775709s
Average Latency	398.453395ms
Throughput	125.05 requests/second

[github-actions]

X-Test Results

✅ go-pull-3232
✅ go-v0.9.0
✅ java-pull-3232
✅ js-pull-3232
✅ java-v0.9.0
test-cases-mapping-report
bats-test-results
✅ js-v0.9.0
cukes-report
opentdfplatformGOI5R6.dockerbuild

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@protocol/go/authorization/v2/entity_identifier_test.go`:
- Around line 34-98: The three tests TestForClientID, TestForEmail, and
TestForUserName duplicate the same assertions; refactor them into a single
table-driven test (e.g., TestEntityChainConstructors) that iterates over cases
with fields: name, constructor (ForClientID/ForEmail/ForUserName), input string,
a small checker to extract the expected value from the entity (using type
assertions to *entity.Entity_ClientId, *entity.Entity_EmailAddress,
*entity.Entity_UserName), and expected value; inside each subtest call the
constructor, use extractEntityChain and chain.GetEntities(), assert len==1, run
the checker and compare the returned value to expected, and assert
e.GetCategory() == entity.Entity_CATEGORY_SUBJECT to replace the three existing
tests.
- Around line 1-107: Add edge-case unit tests that exercise empty-string inputs
and ensure constructors behave as intended: create tests like
TestForClientID_EmptyString, TestForEmail_EmptyString,
TestForUserName_EmptyString and TestForToken_EmptyString that call
ForClientID(""), ForEmail(""), ForUserName(""), ForToken("") respectively, use
extractEntityChain(t, eid) (or GetIdentifier for Token) to retrieve the created
entity, assert the chain/entities length is still correct (e.g., 1) and that the
specific field (ClientId, EmailAddress, UserName, Token.Jwt) equals the empty
string (or whatever the defined behavior should be), and for WithRequestToken
consider a test asserting that WithRequestToken still returns true/false as
expected; make sure to follow existing test patterns (extractEntityChain, type
assertions like (*entity.Entity_ClientId), and category checks) to keep
consistency.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 77800d08-e88c-4e00-81e7-569b52d2fa87

📥 Commits

Reviewing files that changed from the base of the PR and between 780ef79 and 3803d27.

📒 Files selected for processing (1)

• protocol/go/authorization/v2/entity_identifier_test.go

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	175.812045ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	83.027364ms

Benchmark Statistics

Name	№ Requests	Avg Duration	Min Duration	Max Duration

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	403.147059ms
Throughput	248.05 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	42.545200729s
Average Latency	423.652456ms
Throughput	117.52 requests/second

[github-actions]

X-Test Results

✅ go-pull-3232
✅ java-pull-3232
✅ go-v0.9.0
✅ js-pull-3232
✅ java-v0.9.0
✅ js-v0.9.0
test-cases-mapping-report
bats-test-results
cukes-report
opentdfplatformCGRWL8.dockerbuild

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	199.213828ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	100.622403ms

Benchmark Statistics

Name	№ Requests	Avg Duration	Min Duration	Max Duration

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	382.076638ms
Throughput	261.73 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	40.814419605s
Average Latency	405.593548ms
Throughput	122.51 requests/second

[github-actions]

X-Test Failure Report

✅ java-pull-3232
✅ go-v0.9.0
✅ js-pull-3232
✅ java-v0.9.0
test-cases-mapping-report
✅ js-v0.9.0
bats-test-results
cukes-report
opentdfplatformVOA47Z.dockerbuild

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	203.404755ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

Metric	Value
Approved Decision Requests	1000
Denied Decision Requests	0
Total Time	99.689247ms

Benchmark Statistics

Name	№ Requests	Avg Duration	Min Duration	Max Duration

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	384.677875ms
Throughput	259.96 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	40.444486178s
Average Latency	402.623917ms
Throughput	123.63 requests/second

[github-actions]

X-Test Results

✅ go-pull-3232
✅ go-v0.9.0
✅ java-pull-3232
✅ js-pull-3232
✅ java-v0.9.0
✅ js-v0.9.0
test-cases-mapping-report
bats-test-results
cukes-report
opentdfplatformTKZ8TN.dockerbuild

[marythought]

Implementation approach is pending decision on ADR: Proto helper code generation. The current PR places helpers in the sdk package as an interim solution; the final location will depend on the ADR outcome.