Skip to content

Conversation

perrozzi
Copy link
Contributor

@perrozzi perrozzi commented Sep 15, 2025

Key Features Added

🔐 Auth_tools Support

HTTP Plugin: Added auth_tools field to HttpCallTemplate for tool-specific authentication
Text Plugin: Added auth_tools support for local OpenAPI specs
Smart Authentication: Compatible auth schemes use real credentials, incompatible ones use placeholders
Public Endpoints: Remain accessible without authentication requirements

🤖 Auto-Discovery of Authentication Requirements

AuthToolsConfig: New wrapper class with auto_discover and verify_auth options
Endpoint Testing: Automatically tests endpoints with unauthenticated requests
Smart Classification:
• 200/2xx → Public endpoint (no auth needed)
• 401/403 → Requires authentication
• Other → Assumes public for safety
Credential Verification: Optional validation that provided auth actually works
Override Specs: Ignores potentially incorrect OpenAPI security definitions

🧪 Test Infrastructure Fixes

Pytest Fixtures: Resolved aiohttp_client dependency issues in HTTP tests
Test Coverage: All 163 tests now pass without conflicts
Comprehensive Testing: Added auth_tools integration tests and auto-discovery test suite

Technical Implementation

Authentication Logic

• Analyzes OpenAPI security schemes vs provided auth_tools
• convert_async() method with auto-discovery support
• Applies authentication only to compatible/required endpoints
• Maintains backward compatibility (auth_tools is optional)
• Preserves existing behavior for public APIs

Auto-Discovery Process

  1. Test Endpoints: Makes unauthenticated requests to each endpoint
  2. Classify Responses: Determines actual auth requirements vs spec
  3. Apply Authentication: Only adds auth to endpoints returning 401/403
  4. Verify Credentials: Tests that provided auth actually works (optional)
  5. Log Issues: Reports when auth doesn't work for specific endpoints

Plugin Support

HTTP Plugin: Full auth_tools support with auto-discovery for remote OpenAPI specs
Text Plugin: Auth_tools support with auto-discovery for local OpenAPI files
Consistent API: Same auth_tools interface across both plugins

Configuration Examples

Basic Auth_tools

{
  "auth_tools": {
    "auth_type": "api_key",
    "api_key": "Bearer ${API_TOKEN}",
    "var_name": "Authorization",
    "location": "header"
  }
}

Auto-Discovery Configuration

{
  "auth_tools": {
    "auth": {
      "auth_type": "api_key", 
      "api_key": "Bearer ${GITHUB_TOKEN}",
      "var_name": "Authorization",
      "location": "header"
    },
    "auto_discover": true,
    "verify_auth": true
  }
}

Documentation Updates

• Updated README.md with auth_tools and auto-discovery configuration examples
• Enhanced plugin-specific documentation
• Added usage examples for both HTTP and text plugins
• Complete auto-discovery guide and benefits

Backward Compatibility

✅ All existing functionality preserved
✅ Optional auth_tools field maintains compatibility
✅ AuthToolsConfig supports both dict and Auth object formats
✅ No breaking changes to existing APIs

Testing

• 163/163 tests passing
• New integration tests for auth_tools functionality
• Comprehensive auto-discovery test suite
• AuthToolsConfig serialization/validation tests
• Comprehensive coverage of authentication scenarios

…eration

- Add auth_tools field to HttpCallTemplate for tool-specific authentication
- Implement compatibility checking between OpenAPI security schemes and auth_tools
- Apply real credentials when compatible, use placeholders when incompatible
- Preserve existing behavior for public endpoints (no auth required)
- Add comprehensive test coverage for all authentication scenarios
- Update documentation with auth_tools examples and usage
- Maintain full backward compatibility
- Update HttpCallTemplate, HttpCommunicationProtocol, and OpenApiConverter
- Add auth_tools examples to README.md
- Update existing tests for new auth_tools parameter
- Add integration test for auth_tools field functionality
- Fix aiohttp_client fixture usage by properly injecting app dependency
- Ensure all test fixtures receive required parameters correctly
- All 153 tests now pass without fixture conflicts
- Add auth_tools field to TextCallTemplate for OpenAPI-generated tools
- Pass auth_tools to OpenApiConverter when processing local OpenAPI specs
- Update documentation to reflect new authentication capabilities
- Add test coverage for auth_tools functionality
- Maintains backward compatibility (auth_tools is optional)

This allows text plugin to apply authentication to tools generated from
local OpenAPI specifications, enabling secure API calls while keeping
file access authentication-free.
@perrozzi perrozzi force-pushed the feature/x-utcp-auth-v2 branch from 325a20b to 1589bdf Compare September 15, 2025 22:02
@perrozzi
Copy link
Contributor Author

addresses #67

Copy link
Contributor

@cubic-dev-ai cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 issues found across 11 files

Prompt for AI agents (all 2 issues)

Understand the root cause of the following 2 issues and fix them.


<file name="plugins/communication_protocols/text/src/utcp_text/text_call_template.py">

<violation number="1" location="plugins/communication_protocols/text/src/utcp_text/text_call_template.py:27">
auth_tools lacks serializer/validator; dict configs will lose critical fields when validated as Auth. Add field_serializer/field_validator using AuthSerializer like the existing auth field.</violation>
</file>

<file name="README.md">

<violation number="1" location="README.md:379">
Misleading comment: &#39;auth&#39; is described as OpenAPI spec URL auth in a tool call example; should describe HTTP request auth.</violation>
</file>

React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.

README.md Outdated
"http_method": "POST", // Required, default: "GET"
"content_type": "application/json", // Optional, default: "application/json"
"auth": { // Optional, example using ApiKeyAuth for a Bearer token. The client must prepend "Bearer " to the token.
"auth": { // Optional, authentication for accessing the OpenAPI spec URL (example using ApiKeyAuth for Bearer token)
Copy link
Contributor

@cubic-dev-ai cubic-dev-ai bot Sep 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Misleading comment: 'auth' is described as OpenAPI spec URL auth in a tool call example; should describe HTTP request auth.

Prompt for AI agents
Address the following comment on README.md at line 379:

<comment>Misleading comment: &#39;auth&#39; is described as OpenAPI spec URL auth in a tool call example; should describe HTTP request auth.</comment>

<file context>
@@ -376,12 +376,18 @@ Configuration examples for each protocol. Remember to replace `provider_type` wi
   &quot;http_method&quot;: &quot;POST&quot;, // Required, default: &quot;GET&quot;
   &quot;content_type&quot;: &quot;application/json&quot;, // Optional, default: &quot;application/json&quot;
-  &quot;auth&quot;: { // Optional, example using ApiKeyAuth for a Bearer token. The client must prepend &quot;Bearer &quot; to the token.
+  &quot;auth&quot;: { // Optional, authentication for accessing the OpenAPI spec URL (example using ApiKeyAuth for Bearer token)
     &quot;auth_type&quot;: &quot;api_key&quot;,
     &quot;api_key&quot;: &quot;Bearer $API_KEY&quot;, // Required
</file context>
Suggested change
"auth": { // Optional, authentication for accessing the OpenAPI spec URL (example using ApiKeyAuth for Bearer token)
"auth": { // Optional, authentication for the HTTP request (example using ApiKeyAuth for Bearer token)

✅ Addressed in 7933fd4

perrozzi and others added 2 commits September 15, 2025 22:27
- Add field_serializer and field_validator for auth_tools in TextCallTemplate
- Add field_serializer and field_validator for both auth and auth_tools in HttpCallTemplate
- Use AuthSerializer.validate_dict() for proper dict-to-Auth conversion
- Add comprehensive test coverage for auth_tools serialization
- Ensures dict configurations preserve all critical authentication fields
- All 155 tests pass with proper field validation
@h3xxit h3xxit merged commit 6a35aab into dev Sep 21, 2025
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants