feat(policy): Add list key mappings rpc.

[c-r33d]

Proposed Changes

1.) Add the ability to list key mappings for either:

• All keys
• A specific key

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 @c-r33d, 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 significant new feature to the policy service: the ability to list key mappings. This enhancement provides crucial insight into how keys are associated with policy objects, improving transparency and manageability of policy enforcement within the system. The changes span across the protobuf definitions, database layer, service implementation, SDK, and documentation, ensuring a complete and well-tested solution.

Highlights

• New RPC Endpoint: List Key Mappings: I've introduced a new RPC endpoint, ListKeyMappings, within the KeyAccessServerRegistryService. This endpoint allows users to retrieve key mappings, providing visibility into which keys are associated with specific policy objects (namespaces, attributes, and values).
• Flexible Querying for Key Mappings: The new ListKeyMappings RPC supports flexible querying. You can list all key mappings, or filter them by a specific system key ID, or by a combination of a Key ID (KID) and a Key Access Server (KAS) identifier (KAS ID, URI, or Name). Pagination is also supported for managing large result sets.
• Database Query and Data Model Enhancements: To support the new RPC, I've implemented a comprehensive SQL query (listKeyMappings) that efficiently retrieves and aggregates key-to-policy-object mappings from the database. New protobuf messages (KeyMapping, MappedPolicyObject, ListKeyMappingsRequest, ListKeyMappingsResponse) have been defined to structure the request and response data.
• SDK and Documentation Updates: The Go SDK client has been updated to include the new ListKeyMappings method, making it accessible for client applications. Corresponding documentation in docs/grpc/index.html has also been generated to reflect the new RPC and its data structures.
• Comprehensive Test Coverage: Extensive integration and unit tests have been added to validate the functionality and robustness of the ListKeyMappings RPC, covering various success and error scenarios, including invalid inputs, different filtering combinations, and pagination.

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 is currently in preview and 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 to provide feedback.

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.

---

A key, a map, a policy's hold, New paths for data, brave and bold. With queries deep, and code so neat, All mappings found, a task complete.

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 a new RPC ListKeyMappings to list key mappings for all keys or a specific key. The changes span across protobuf definitions, service implementation, database queries, SDK, and documentation. The implementation is robust, with good test coverage for various scenarios, including edge cases and pagination. The new database query is well-structured using CTEs for clarity. I've included a few suggestions to improve maintainability, clarity, and efficiency in the protobuf definitions, integration tests, and the SQL query. These are not critical but would enhance the overall quality of the code. Great work on adding this new functionality and the comprehensive tests!

[github-actions]

Benchmark results, click to expand

Benchmark authorization.GetDecisions Results:

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

Benchmark authorization.v2.GetMultiResourceDecision Results:

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

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	349.084114ms
Throughput	286.46 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	37.916197887s
Average Latency	377.619548ms
Throughput	131.87 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	26.322972301s
Average Latency	262.285442ms
Throughput	189.95 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	165.718282ms

Benchmark authorization.v2.GetMultiResourceDecision Results:

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

Standard Benchmark Metrics Skipped or Failed

Bulk Benchmark Results

Metric	Value
Total Decrypts	100
Successful Decrypts	100
Failed Decrypts	0
Total Time	341.124136ms
Throughput	293.15 requests/second

TDF3 Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	36.661490157s
Average Latency	365.011019ms
Throughput	136.38 requests/second

NANOTDF Benchmark Results:

Metric	Value
Total Requests	5000
Successful Requests	5000
Failed Requests	0
Concurrent Requests	50
Total Time	25.712395431s
Average Latency	255.861726ms
Throughput	194.46 requests/second

[c-r33d]

/backport

[opentdf-automation]

Created backport PR for release/service/v0.7:

• feat(policy): Add list key mappings rpc. [backport to release/service/v0.7] #2595 with remaining conflicts!

Please cherry-pick the changes locally and resolve any conflicts.

git fetch origin backport-2533-to-release/service/v0.7
git worktree add --checkout .worktree/backport-2533-to-release/service/v0.7 backport-2533-to-release/service/v0.7
cd .worktree/backport-2533-to-release/service/v0.7
git reset --hard HEAD^
git cherry-pick -x fbc2724a066b5e4121838a958cb926a1ab5bdcde
git push --force-with-lease