Update Policy components documentation #146

jp-ayyappan · 2025-08-25T13:34:25Z

TBD

gemini-code-assist

Summary of Changes

Hello @jp-ayyappan, 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 provides a substantial update to the OpenTDF platform's documentation, primarily focusing on the Policy components, including a complete overhaul of the Key Management section. It introduces new V2 APIs for authorization, updates existing code samples across multiple languages, and clarifies the platform's architecture by adding the Entity Resolution Service. This ensures the documentation is current, comprehensive, and easier to navigate for users and developers.

Highlights

Comprehensive Key Management Documentation Overhaul: The documentation for OpenTDF's Policy components, particularly the Key Management section, has undergone a comprehensive overhaul. This includes new detailed guides for Base Keys, Key Managers, and Key Mappings, providing a much clearer understanding of the system's cryptographic key handling.
New Migration Guide for KAS Grants to Key Mappings: A dedicated guide has been introduced to assist users in migrating from the legacy KAS Grants system to the new Key Mappings. This new document outlines the timeline, differences, and step-by-step process for a smooth transition.
Updated Platform Architecture with Entity Resolution Service: The platform's architecture documentation has been updated to reflect the inclusion of the Entity Resolution Service as a core component. This clarifies how identity providers integrate with the OpenTDF platform for authorization decisions.
Refactored and Expanded Authorization API Code Samples: Code samples for Authorization APIs (GetDecision, GetEntitlements) across Go, Java, and JavaScript have been extensively refactored and expanded. This includes the introduction of V2 API examples and clear demarcation of V1 APIs as legacy, ensuring developers use the most current and recommended approaches.
Implementation of Markdown Linting for Documentation Quality: A new .markdownlint.yaml configuration file has been added to enforce consistent markdown formatting and quality across the documentation. This improves readability and maintainability of the documentation content.

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.

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 provides a significant and valuable update to the documentation, especially concerning the new key management architecture. The new documents are comprehensive, well-structured, and include helpful examples and migration guides. I've identified a few minor areas for improvement, mainly related to consistency in code samples and formatting in configuration files, to enhance clarity and correctness.

gemini-code-assist · 2025-08-25T13:36:51Z

.markdownlint.yaml

+    - summary
+    - details
+    - strong
+MD013: false # Line length


For consistency and to adhere to POSIX standards, it's a good practice to end files with a newline character.

MD013: false # Line length

gemini-code-assist · 2025-08-25T13:36:52Z

code_samples/authorization/get_decision.mdx

+  const platformUrl = "http://localhost:8080";
+
+  // Assume you have an existing access token
+  const accessToken = "your-refresh-token-here";


The value assigned to the accessToken constant is misleading. It's set to "your-refresh-token-here", but an access token is expected here, not a refresh token. Using a refresh token directly for authorization would be incorrect.

const accessToken = "your-access-token-here";

gemini-code-assist · 2025-08-25T13:36:52Z

docs/sdks/authorization.mdx

+import { create } from '@bufbuild/protobuf';
+import { GetEntitlementsRequestSchema, EntitySchema, Entity_CategorySchema } from '@opentdf/sdk/platform';
+
+async function getEntitlements(platformClient) {
+  // Assume we have an access token representing the user
+  const accessToken = 'user-access-token-here';
+
+  const request = create(GetEntitlementsRequestSchema, {
+    entities: [
+      create(EntitySchema, {
+        id: 'user-bob',
+        entityType: {
+          case: 'emailAddress',
+          value: 'bob@OrgA.com'
+        },
+        category: Entity_CategorySchema.SUBJECT
+      })
+    ]
+  });
+
+  const response = await platformClient.v1.authorization.getEntitlements(request);
+
+  response.entitlements.forEach(entitlement => {
+    console.log('Entitled to:', entitlement.attributeValueFqns);
+  });
+}
+```


The JavaScript example for getEntitlements uses the V1 API, which is inconsistent with the Go and Java examples that demonstrate the recommended V2 API. The V1 GetEntitlements request takes a list of entities, whereas the V2 request uses an EntityIdentifier. To improve consistency, please update this example to use the V2 API or clearly label it as a legacy V1 example.

gemini-code-assist · 2025-08-25T13:36:52Z

docs/sdks/authorization.mdx

+        // Make authorization decision
+        decision := makeAuthorizationDecision(sdk, entity, "access", resourceAttrs)
+
+        if decision == authorization.DecisionResponse_DECISION_PERMIT {


This Go middleware example uses the V1 decision enum (authorization.DecisionResponse_DECISION_PERMIT). To maintain consistency with the rest of the document, which recommends the V2 API, it would be better to use the V2 enum (authorizationv2.Decision_DECISION_PERMIT) here.

if decision == authorizationv2.Decision_DECISION_PERMIT {

…encies - Fix API version inconsistencies in authorization examples - Update Get Entitlements to use v2 API with EntityIdentifier - Update Get Decision to use v2 API with proper resource structure - Replace authorization.mdx with comprehensive documentation - Add complete JavaScript/TypeScript examples - Include best practices, error handling, and integration patterns - Add performance optimization and security guidance Addresses community requests for better authz documentation and fills gaps identified in issues #15 and #25.

…stency - Fix trailing space in Java clientSecret string literal - Correct misleading comment for WithComprehensiveHierarchy parameter - Update protobuf field access to use getter methods instead of direct access - Fix bulk decision examples to use proper BoolValue handling - Standardize Java endpoint to http://localhost:9002 for consistency - Fix error handling function syntax errors and unreachable code All examples now follow protobuf best practices and have consistent formatting.

**High Priority Issues Fixed:** - Updated Java GetDecision example to use v2 API instead of v1 API - Updated Java GetEntitlements example to use v2 API with EntityIdentifier - Both Java examples now use consistent v2 API patterns matching Go examples **Medium Priority Issues Fixed:** - Fixed Java code indentation consistency (standardized 4-space continuation indent) - Added missing Java and JavaScript examples to complete language coverage: - Entitlements with Scope section - Bulk Authorization Decisions section - Token-Based Authentication Example section **Documentation Improvements:** - All sections now have complete Go, Java, and JavaScript examples - Java examples use proper v2 API patterns with EntityIdentifier - Consistent code formatting across all language examples - Enhanced developer experience with comprehensive language coverage Addresses all issues raised in the latest Gemini Code Assist review.

This refactors the architecture page to improve readability and navigation. The layout is updated to a single column, the diagram is reoriented, and all components and NIST terms are now linked to their respective pages.

jp-ayyappan requested a review from a team as a code owner August 25, 2025 13:34

gemini-code-assist bot reviewed Aug 25, 2025

View reviewed changes

jp-ayyappan mentioned this pull request Aug 25, 2025

Improve authorization SDK documentation and fix API version inconsistencies #140

Merged

4 tasks

jp-ayyappan added 5 commits August 25, 2025 22:09

Initial commit

ac457b5

jp-ayyappan force-pushed the docs/update-policy-key-management-features branch from 8cbe46a to 4e8410b Compare August 26, 2025 02:19

jp-ayyappan closed this Aug 26, 2025

jp-ayyappan deleted the docs/update-policy-key-management-features branch August 26, 2025 02:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Update Policy components documentation #146

Update Policy components documentation #146

Uh oh!

jp-ayyappan commented Aug 25, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Aug 25, 2025

Uh oh!

gemini-code-assist bot Aug 25, 2025

Uh oh!

gemini-code-assist bot Aug 25, 2025

Uh oh!

gemini-code-assist bot Aug 25, 2025

Uh oh!

Uh oh!

Update Policy components documentation #146

Update Policy components documentation #146

Uh oh!

Conversation

jp-ayyappan commented Aug 25, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

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!

gemini-code-assist bot Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!