feat: add Authority Envelope SDK wrappers (RFC-008) (#60)

* feat: add Authority Envelope SDK wrappers (RFC-008)

Adds envelope creation, derivation, and transport header generation to the
Python SDK, wrapping the new gRPC surface added in capiscio-core PR #70.

Changes:
- Regenerate proto stubs with CreateEnvelope, DeriveEnvelope,
  BuildTransportHeaders, VerifyEnvelopeChain RPCs and 8 new messages
- Add low-level gRPC client wrappers in _rpc/client.py:
  - create_envelope(): Create root envelopes (§6.1)
  - derive_envelope(): Derive child envelopes with hash linking (§6.3)
  - build_transport_headers(): Encode chains to HTTP headers (§15.1-§15.3)
- Add high-level SimpleGuard API methods:
  - create_envelope(): Simplified root envelope creation
  - derive_envelope(): Simplified child envelope derivation
  - make_delegation_headers(): Combined badge + chain headers for requests
- Add 14 unit tests covering all envelope operations

Tests cover: basic creation, constraints serialization, enforcement mode,
error propagation, derivation with narrowing, header generation with/without
badge maps.

* fix(sdk): type annotation and protobuf version consistency

- Use list[str] instead of bare list in make_delegation_headers
- Align simpleguard_pb2.py runtime version check to 6.33.5 to match
  all other generated pb2 files and the protobuf>=6.33.5 dependency

Author: beonde

capiscio_sdk/_rpc/client.py

@@ -1346,6 +1346,125 @@ def init(
             "registered": response.registered,
         }, None
 
+    def create_envelope(
+        self,
+        key_id: str,
+        subject_did: str,
+        capability_class: str,
+        delegation_depth_remaining: int,
+        issuer_badge_jti: str,
+        txn_id: str = "",
+        expires_in_seconds: int = 3600,
+        constraints_json: str = "",
+        subject_badge_jti: str = "",
+        enforcement_mode_min: str = "",
+    ) -> tuple[str, str, str, Optional[str]]:
+        """Create a root Authority Envelope (RFC-008 §6.1).
+
+        Args:
+            key_id: Key to sign with (from key store)
+            subject_did: DID of the agent receiving authority
+            capability_class: e.g., "tools.database.read"
+            delegation_depth_remaining: How many further delegations allowed
+            issuer_badge_jti: JTI of the issuer's badge
+            txn_id: Transaction ID (auto-generated if empty)
+            expires_in_seconds: TTL from now (default: 3600)
+            constraints_json: Optional JSON constraints object
+            subject_badge_jti: JTI of the subject's badge (optional)
+            enforcement_mode_min: Optional minimum enforcement mode
+
+        Returns:
+            Tuple of (envelope_jws, envelope_id, issuer_did, error_message)
+        """
+        request = simpleguard_pb2.CreateEnvelopeRequest(
+            key_id=key_id,
+            subject_did=subject_did,
+            capability_class=capability_class,
+            delegation_depth_remaining=delegation_depth_remaining,
+            txn_id=txn_id,
+            expires_in_seconds=expires_in_seconds,
+            constraints_json=constraints_json,
+            issuer_badge_jti=issuer_badge_jti,
+            subject_badge_jti=subject_badge_jti,
+            enforcement_mode_min=enforcement_mode_min,
+        )
+        response = self._stub.CreateEnvelope(request)
+        error = response.error_message if response.error_message else None
+        return response.envelope_jws, response.envelope_id, response.issuer_did, error
+
+    def derive_envelope(
+        self,
+        parent_envelope_jws: str,
+        key_id: str,
+        subject_did: str,
+        capability_class: str,
+        delegation_depth_remaining: int,
+        issuer_badge_jti: str,
+        expires_in_seconds: int = 1800,
+        constraints_json: str = "",
+        subject_badge_jti: str = "",
+        enforcement_mode_min: str = "",
+    ) -> tuple[str, str, str, Optional[str]]:
+        """Derive a child Authority Envelope from a parent (RFC-008 §6.3).
+
+        Args:
+            parent_envelope_jws: Parent envelope JWS
+            key_id: Key to sign child with
+            subject_did: DID of the next delegate
+            capability_class: Must be equal or narrower than parent
+            delegation_depth_remaining: Must be < parent's depth
+            issuer_badge_jti: JTI of the child issuer's own badge
+            expires_in_seconds: TTL from now (default: 1800)
+            constraints_json: Must be equal or more restrictive
+            subject_badge_jti: JTI of the subject's badge
+            enforcement_mode_min: Optional minimum enforcement mode
+
+        Returns:
+            Tuple of (envelope_jws, envelope_id, parent_authority_hash, error_message)
+        """
+        request = simpleguard_pb2.DeriveEnvelopeRequest(
+            parent_envelope_jws=parent_envelope_jws,
+            key_id=key_id,
+            subject_did=subject_did,
+            capability_class=capability_class,
+            delegation_depth_remaining=delegation_depth_remaining,
+            expires_in_seconds=expires_in_seconds,
+            constraints_json=constraints_json,
+            subject_badge_jti=subject_badge_jti,
+            issuer_badge_jti=issuer_badge_jti,
+            enforcement_mode_min=enforcement_mode_min,
+        )
+        response = self._stub.DeriveEnvelope(request)
+        error = response.error_message if response.error_message else None
+        return response.envelope_jws, response.envelope_id, response.parent_authority_hash, error
+
+    def build_transport_headers(
+        self,
+        chain: list[str],
+        badge_map: Optional[dict[str, str]] = None,
+    ) -> tuple[str, str, str, Optional[str]]:
+        """Build RFC-008 §15 transport headers for a delegation chain.
+
+        Args:
+            chain: Ordered JWS array [root, ..., leaf]
+            badge_map: DID → badge JWS for intermediate agents
+
+        Returns:
+            Tuple of (authority_header, authority_chain_header, badge_map_header, error_message)
+        """
+        request = simpleguard_pb2.BuildTransportHeadersRequest(
+            chain=chain,
+            badge_map=badge_map or {},
+        )
+        response = self._stub.BuildTransportHeaders(request)
+        error = response.error_message if response.error_message else None
+        return (
+            response.authority_header,
+            response.authority_chain_header,
+            response.badge_map_header,
+            error,
+        )
+
 
 class MCPClient:
     """Client wrapper for MCPService (RFC-006 Tool Authority + RFC-007 Server Identity).