RFC-002: Trust Badge gRPC Client by beonde · Pull Request #7 · capiscio/capiscio-sdk-python

beonde · 2025-12-10T03:30:39Z

Summary

Adds a thin gRPC client that connects to capiscio-core's gRPC server, enabling the Python SDK to leverage the full Go implementation for Trust Badge functionality.

Architecture

This client is designed to be a thin wrapper that delegates all cryptographic operations to the Go core via gRPC:

┌─────────────────────────────────────┐
│  Python Application                 │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│  capiscio_sdk                       │
│  ├── _rpc/client.py                 │  ← CapiscioRPCClient
│  └── _rpc/gen/capiscio/v1/          │  ← Generated protobuf code
└────────────┬────────────────────────┘
             │  gRPC
┌────────────▼────────────────────────┐
│  capiscio-core (Go gRPC Server)     │
└─────────────────────────────────────┘

Changes

Generated Protobuf Code (`capiscio_sdk/_rpc/gen/`)

All *_pb2.py and *_pb2_grpc.py files for 7 services:

badge_pb2.py / badge_pb2_grpc.py
did_pb2.py / did_pb2_grpc.py
trust_pb2.py / trust_pb2_grpc.py
revocation_pb2.py / revocation_pb2_grpc.py
scoring_pb2.py / scoring_pb2_grpc.py
simpleguard_pb2.py / simpleguard_pb2_grpc.py
registry_pb2.py / registry_pb2_grpc.py

RPC Client (`capiscio_sdk/_rpc/`)

client.py: CapiscioRPCClient with typed service wrappers
process.py: ProcessManager to spawn/manage the Go binary

Usage

from capiscio_sdk._rpc.client import CapiscioRPCClient

# Connect to running server
client = CapiscioRPCClient("localhost:50051")

# Use DID service
result = client.did.parse("did:web:example.com")
print(result.domain)  # "example.com"

# Use Registry service  
pong = client.registry.ping()
print(pong.message)  # "pong"

Services Available

Service	Description
`BadgeService`	Trust Badge signing/verification
`DIDService`	did:web parsing and construction
`TrustStoreService`	Key management
`RevocationService`	Key/badge revocation
`ScoringService`	Agent card validation
`SimpleGuardService`	Basic signing
`RegistryService`	Agent discovery

Dependencies

grpcio>=1.60.0
protobuf>=4.25.0

This adds a thin gRPC client that connects to capiscio-core's gRPC server, enabling Python SDK to leverage the full Go implementation. ## Changes ### Generated Protobuf Code (capiscio_sdk/_rpc/gen/) - All *_pb2.py and *_pb2_grpc.py files for 7 services - Generated from capiscio-core proto files ### RPC Client (capiscio_sdk/_rpc/) - client.py: CapiscioRPCClient with service wrappers - process.py: ProcessManager to spawn/manage Go binary ## Services Available - BadgeService: Trust Badge signing/verification - DIDService: did:web parsing and construction - TrustStoreService: Key management - RevocationService: Key/badge revocation - ScoringService: Agent card validation - SimpleGuardService: Basic signing - RegistryService: Agent discovery Implements: RFC-002 Trust Badge Depends-on: capiscio/capiscio-core#17

github-actions · 2025-12-10T03:31:31Z

✅ All checks passed! Ready for review.

github-actions · 2025-12-10T03:31:46Z

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

Copilot

Pull request overview

This PR adds a gRPC client implementation for the Python SDK to communicate with the capiscio-core Go server, enabling Trust Badge functionality through remote procedure calls rather than native Python implementations.

Key Changes:

Generated protobuf/gRPC code for 7 services (Badge, DID, TrustStore, Revocation, Scoring, SimpleGuard, Registry)
Process manager to spawn and manage the Go binary lifecycle
High-level Python client wrapper with typed service interfaces

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
pyproject.toml	Adds grpcio and protobuf dependencies
capiscio_sdk/_rpc/process.py	Process manager for Go binary lifecycle management
capiscio_sdk/_rpc/client.py	Main RPC client with service wrappers
capiscio_sdk/_rpc/gen/capiscio/v1/*_pb2.py	Generated protobuf message definitions
capiscio_sdk/_rpc/gen/capiscio/v1/*_pb2_grpc.py	Generated gRPC service stubs
capiscio_sdk/_rpc/init.py	Package exports
capiscio_sdk/_rpc/gen//init**.py	Module initialization for generated code

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…ement - SimpleGuardClient: added sign_attached, verify_attached, generate_key_pair, load_key, export_key, get_key_info methods - SimpleGuardRPC: new drop-in replacement class for native SimpleGuard - Provides identical interface for easy migration to gRPC backend

github-actions · 2025-12-10T03:50:30Z

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

github-actions · 2025-12-10T03:50:44Z

✅ All checks passed! Ready for review.

beonde · 2025-12-10T03:52:26Z

PR Summary for Review

This PR adds gRPC client infrastructure to call Go core via the new RPC server.

What's included:

Generated Protobuf Code (capiscio_sdk/_rpc/proto/)

Python stubs for all 7 services
Generated via buf generate

Client Wrappers (capiscio_sdk/_rpc/client.py)

Client	Methods
`DIDClient`	`parse()`, `validate()`, `new_capiscio_agent_did()`, `is_agent_did()`
`SimpleGuardClient`	`sign()`, `verify()`, `sign_attached()`, `verify_attached()`, `generate_key_pair()`, `load_key()`, `export_key()`, `get_key_info()`
`TrustStoreClient`	`add_key()`, `remove_key()`, `get_key()`, `list_keys()`, `is_trusted()`, `import_from_directory()`, `export_to_directory()`, `clear()`
`BadgeClient`	`sign_badge()`, `verify_badge()`, `parse_badge()`
`RegistryClient`	`ping()`

Drop-in Replacement (capiscio_sdk/simple_guard_rpc.py)

SimpleGuardRPC class with identical interface to native SimpleGuard
Easy migration path: just swap the import

Usage

from capiscio_sdk._rpc.client import CapiscioRPCClient

client = CapiscioRPCClient(address='localhost:50051')
client.connect()
client.simpleguard.sign_attached(payload=b'data', key_id='my-key')

Testing

Integration tests passing against Go server ✅

- Fix _initialized check to use hasattr (prevents AttributeError) - Fix path calculation for dev binary (was one level too deep) - Remove unused imports (signal, sys) - Add explanatory comment for except OSError pass

github-actions · 2025-12-10T04:04:22Z

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

github-actions · 2025-12-10T04:04:39Z

✅ All checks passed! Ready for review.

Copilot

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

capiscio_sdk/simple_guard_rpc.py:92

Variable payload_bytes is not used.

        payload_bytes = json.dumps(payload).encode("utf-8")

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-10T04:07:03Z

+        card_data = {
+            "agent_id": self.agent_id,
+            "public_keys": [{
+                "kty": "OKP",
+                "crv": "Ed25519",
+                "kid": self.signing_kid,
+                "use": "sig",
+                # Note: x would need to be extracted from PEM
+            }],


The _update_agent_card_with_pem method creates an agent card with incomplete JWK data. The public key JWK is missing the required 'x' field (line 251 comment notes this), which will result in an invalid agent card. The PEM should be converted to a proper JWK format with all required fields before writing the agent-card.json.

Copilot · 2025-12-10T04:07:03Z

+    def sign_badge(
+        self,
+        claims: dict,
+        private_key_jwk: str,
+        key_id: str = "",
+    ) -> tuple[str, dict]:


The return type annotation uses Python 3.10+ syntax (tuple[str, dict]) but this may not be compatible with the project's minimum Python version. Consider using Tuple[str, dict] from the typing module for broader compatibility, or verify that Python 3.10+ is the minimum supported version.

Copilot · 2025-12-10T04:07:04Z

+
+        # Sign via gRPC - use SignAttached which handles timestamps and body hash
+        jws, error = self._client.simpleguard.sign_attached(
+            payload=body_bytes,  # This gets hashed into 'bh' claim


The sign_outbound method incorrectly uses the body parameter as the payload for signing. According to the comment on line 98, the body should be "hashed into 'bh' claim", but the actual JWT payload from the payload argument is being ignored. The payload dictionary should be serialized and used as the payload, while the body should be used for the body hash claim.

Suggested change

payload=body_bytes, # This gets hashed into 'bh' claim

payload=payload_bytes, # The actual JWT payload to sign

body=body_bytes, # This gets hashed into 'bh' claim

Copilot · 2025-12-10T04:07:04Z

+import grpc
+


Import of 'grpc' is not used.

Suggested change

import grpc

Copilot · 2025-12-10T04:07:04Z

+from capiscio_sdk._rpc.gen.capiscio.v1 import common_pb2 as capiscio_dot_v1_dot_common__pb2
+
+


Import of 'capiscio_dot_v1_dot_common__pb2' is not used.

Suggested change

from capiscio_sdk._rpc.gen.capiscio.v1 import common_pb2 as capiscio_dot_v1_dot_common__pb2

Copilot AI review requested due to automatic review settings December 10, 2025 03:30

Copilot started reviewing on behalf of beonde December 10, 2025 03:31 View session

beonde mentioned this pull request Dec 10, 2025

RFC-002: Trust Badge Specification capiscio/capiscio-rfcs#2

Merged

Copilot AI reviewed Dec 10, 2025

View reviewed changes

fix(rpc): address Copilot review comments in process.py

cb40a18

- Fix _initialized check to use hasattr (prevents AttributeError) - Fix path calculation for dev binary (was one level too deep) - Remove unused imports (signal, sys) - Add explanatory comment for except OSError pass

Copilot AI review requested due to automatic review settings December 10, 2025 04:03

Copilot started reviewing on behalf of beonde December 10, 2025 04:04 View session

beonde merged commit e1f9162 into main Dec 10, 2025
15 checks passed

beonde deleted the rfc-002-trust-badge branch December 10, 2025 04:06

Copilot AI reviewed Dec 10, 2025

View reviewed changes

	payload=body_bytes, # This gets hashed into 'bh' claim
	payload=payload_bytes, # The actual JWT payload to sign
	body=body_bytes, # This gets hashed into 'bh' claim

		from capiscio_sdk._rpc.gen.capiscio.v1 import common_pb2 as capiscio_dot_v1_dot_common__pb2

Uh oh!

Conversation

beonde commented Dec 10, 2025

Summary

Architecture

Changes

Generated Protobuf Code (capiscio_sdk/_rpc/gen/)

RPC Client (capiscio_sdk/_rpc/)

Usage

Services Available

Dependencies

Related

Uh oh!

github-actions Bot commented Dec 10, 2025

Uh oh!

github-actions Bot commented Dec 10, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Dec 10, 2025

Uh oh!

github-actions Bot commented Dec 10, 2025

Uh oh!

beonde commented Dec 10, 2025

PR Summary for Review

What's included:

Usage

Testing

Uh oh!

github-actions Bot commented Dec 10, 2025

Uh oh!

github-actions Bot commented Dec 10, 2025

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Generated Protobuf Code (`capiscio_sdk/_rpc/gen/`)

RPC Client (`capiscio_sdk/_rpc/`)