Development: Add documentation for tool tokens
#10276
Conversation
WalkthroughThe changes update the server development guidelines by introducing a new authorization annotation, Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant Server
participant AuthHandler
Client->>Server: API Request (with/without tool token)
Server->>AuthHandler: Validate tool token & @AllowedTools annotation
AuthHandler-->>Server: Return authorization status
Server-->>Client: Send response (access granted/denied)
Possibly related issues
Suggested labels
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/dev/guidelines/server.rst (2)
465-469: Update to Implicit Pre-Authorization AnnotationsThe addition of the
AllowedTools(ToolTokenType.__)bullet clearly signals that tool-based requests must be explicitly whitelisted. This is a good enhancement to enforce the Principle of Least Privilege. Please ensure that elsewhere in the project any endpoints that can be accessed by tool tokens are updated accordingly, and consider clarifying in related documentation thatToolTokenType.__is a placeholder which must be replaced with a concrete token type when implemented.
498-536: New "Tool-Based Authorization Annotations" SectionThis newly added section comprehensively explains the purpose and usage of the
@AllowedToolsannotation. The section breaks down how tool tokens are handled versus regular requests, provides clear examples (including code blocks demonstrating proper usage), and outlines best practices. A minor suggestion:
- Consider adding a brief note that
ToolTokenType.__in the earlier section is a placeholder and should be replaced by actual tool types (e.g.,ToolTokenType.SCORPIOorToolTokenType.VSCODE).Otherwise, the content is well-organized and aligns with the project's security and documentation standards.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/dev/guidelines/server.rst(2 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Codacy Static Code Analysis
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/dev/guidelines/server.rst (2)
519-523: Documented Best Practices for Tool-Based Authorization
The “Best Practices” block explains that endpoints accepting tool-based requests must be explicitly annotated and encourages adherence to the Principle of Least Privilege. Consider including a brief note advising that any changes to tool token behavior should be mirrored in this documentation to avoid discrepancies over time.
527-530: “How to Get Tool Tokens” Instructional Block
This step-by-step guide succinctly details how to obtain a Tool Token, including verifying the tool type inToolTokenType.javaand sending a POST request to the authentication endpoint. For added clarity, you might consider including a sample response or outlining potential error scenarios.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/dev/guidelines/server.rst(2 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (3)
docs/dev/guidelines/server.rst (3)
464-468: Enhance Implicit Authorization Annotation List
The bullet list under “Implicit pre- and post-authorization annotations” now includes the new “AllowedTools(ToolTokenType.__)” annotation. The description clearly explains its role in restricting tool-based requests. Ensure that the language here is consistent with later detailed sections and that it aligns with the implementation in ToolTokenType.java.
498-508: New “Tool-Based Authorization Annotations” Section Added
This section introduces and explains the@AllowedToolsannotation in a clear and accessible way. The header and accompanying description effectively differentiate between requests with and without tool claims. Verify that the inline code formatting (especially for JWT claim examples) renders correctly in the final documentation build.
509-517: Clear “When to Use It?” Guidelines with Example
The “When to Use It?” block provides a concise explanation along with a practical Java code example, demonstrating how to annotate an endpoint using@AllowedTools(ToolTokenType.SCORPIO). Confirm that the example (including the referenced DTO name) reflects the actual structures and naming conventions used in the codebase.
HawKhiem
dismissed stale reviews from coderabbitai[bot] and simonbohnen
via
fbd1f5f
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/dev/guidelines/server.rst (1)
498-537: Review the new Tool-Based Authorization Annotations section.
The newly added section does an excellent job of explaining the use, behavior, and best practices for the@AllowedToolsannotation, along with concrete examples. To further enhance clarity, verify that the placeholders (e.g.,ToolTokenType.__) and examples (e.g.,ToolTokenType.SCORPIO,ToolTokenType.VSCODE) match what is implemented in the codebase. Additionally, consider adding a reference or link toToolTokenType.javafor quick access.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/dev/guidelines/server.rst(2 hunks)
🔇 Additional comments (1)
docs/dev/guidelines/server.rst (1)
465-468: Clarify the new AllowedTools bullet in implicit authorization guidelines.
The new bullet introducingAllowedTools(ToolTokenType.__)clearly indicates the intent to restrict tool-based requests. However, consider clarifying thatToolTokenType.__is a placeholder to be replaced by a specific tool type, ensuring that readers do not mistakenly interpret it as a concrete value.
janthoXO
changed the title
Chore: Add Documentation for Tool TokensGeneral : Add Documentation for Tool Tokens
janthoXO
changed the title
General : Add Documentation for Tool TokensGeneral: Add Documentation for Tool Tokens
krusche
changed the title
General: Add Documentation for Tool TokensDevelopment: Add documentation for tool tokens
Description
Add Documentation to explain Tool Tokens and Authorization for the Tokens. The @AllowedTools Annotation restricts Tool Tokens from only accessing certain routes
Find under Contributor Guide at
Coding and Design Guidelines->Server->REST endpoint best practices for authorization->Tool-Based Authorization Annotationsor at this https://artemis-platform--10276.org.readthedocs.build/en/10276/dev/guidelines/server.html#tool-based-authorization-annotations
Testserver States
You can manage test servers using Helios. Check environment statuses in the environment list. To deploy to a test server, go to the CI/CD page, find your PR or branch, and trigger the deployment.
Review Progress
Documentation Review
Screenshots
Summary by CodeRabbit
Summary by CodeRabbit
@AllowedTools(ToolTokenType.__)annotation to restrict access for tool-based requests.@coderabbitai pause