feat(core): add direct entitlement support

[ryanulit]

Proposed Changes

• adds new DirectEntitlement proto message to be used in the entity resolution protos to support directly entitling a user to resource attribute value FQNs
• updates access PDP logic to process direct entitlements
• adds a new auth service config feature flag to enable/disable direct entitlement processing

Checklist

• I have added or updated unit tests
• I have added or updated integration tests (if appropriate)
• I have added or updated documentation

Testing Instructions

[gemini-code-assist]

Summary of Changes

Hello @ryanulit, 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 direct entitlement support for Virtru SaaS ERS, enhancing the Entity Resolution Service (ERS) to handle entitlements that do not require traditional subject mappings. It achieves this by adding a new DirectEntitlement protobuf message and incorporating it into EntityRepresentation. Furthermore, it refines the attribute resolution logic to support ad-hoc attributes, ensuring that resource attribute values can be processed even if not pre-registered, by dynamically creating synthetic attribute values. This change streamlines entitlement management and improves flexibility in how resources are authorized.

Highlights

• New DirectEntitlement Message: A new Protobuf message, DirectEntitlement, has been introduced. This message defines a fully qualified name (fqn) and a list of actions, enabling the representation of entitlements that do not rely on traditional subject mappings.
• Extended EntityRepresentation: The EntityRepresentation message has been extended to include a repeated DirectEntitlement direct_entitlements field. This allows entities to directly carry entitlement information, streamlining the authorization process.
• Enhanced Token-Based Entity Resolution Request: The CreateEntityChainsFromTokensRequest now accepts a repeated authorization.v2.Resource resources field. This enhancement provides additional context for token-based entity resolution, improving the precision of entitlement decisions.
• Ad-hoc Attribute Resolution: The system can now dynamically handle resource attribute values that are not pre-registered. The getResourceDecisionableAttributes function has been updated to extract values from FQNs and create synthetic AttributeAndValue objects, ensuring broader compatibility with ad-hoc attributes.
• Direct Entitlement Integration in PDP: The Policy Decision Point (PDP) has been updated to process direct_entitlements from EntityRepresentation. This allows FQN-to-action mappings to be directly incorporated into authorization decisions, bypassing the need for complex subject mappings in certain scenarios.

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 in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

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

---

Protobuf defined, Entitlements flow direct, Access now is clear.

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]

Code Review

This pull request introduces support for direct entitlements in the Entity Resolution Service. The changes include updates to the protobuf definitions to support this new feature, and modifications to the policy decision point logic to handle these direct entitlements.

My review has identified a few issues:

• A critical validation issue in the protobuf definition for CreateEntityChainsFromTokensRequest that will cause runtime errors.
• A high-severity issue in helpers.go related to brittle and inefficient FQN parsing.
• A high-severity logic error in pdp.go where direct entitlements overwrite existing entitlements instead of merging them.

I've provided detailed comments and suggestions for each of these points. Addressing them will improve the correctness and robustness of the new feature.

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

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

Benchmark authorization.v2.GetMultiResourceDecision Results:

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

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	350.154852ms
Throughput	285.59 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	36.359749203s
Average Latency	362.264128ms
Throughput	137.51 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	25.294084986s
Average Latency	251.264625ms
Throughput	197.67 requests/second

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

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

Benchmark authorization.v2.GetMultiResourceDecision Results:

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

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	355.18448ms
Throughput	281.54 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	36.761658729s
Average Latency	366.018694ms
Throughput	136.01 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	25.638856868s
Average Latency	255.37729ms
Throughput	195.02 requests/second

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

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

Benchmark authorization.v2.GetMultiResourceDecision Results:

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

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	353.409484ms
Throughput	282.96 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	36.861995144s
Average Latency	366.594957ms
Throughput	135.64 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	25.637280614s
Average Latency	254.901353ms
Throughput	195.03 requests/second

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

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

Benchmark authorization.v2.GetMultiResourceDecision Results:

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

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	362.315877ms
Throughput	276.00 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	36.940155494s
Average Latency	367.860382ms
Throughput	135.35 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	26.159427063s
Average Latency	260.427719ms
Throughput	191.14 requests/second

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

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

Benchmark authorization.v2.GetMultiResourceDecision Results:

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

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	353.523107ms
Throughput	282.87 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	36.948122791s
Average Latency	367.683295ms
Throughput	135.32 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	25.847558282s
Average Latency	257.257145ms
Throughput	193.44 requests/second

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

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

Benchmark authorization.v2.GetMultiResourceDecision Results:

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

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	360.250834ms
Throughput	277.58 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	37.286961113s
Average Latency	371.55612ms
Throughput	134.10 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	25.942797769s
Average Latency	258.359281ms
Throughput	192.73 requests/second