feat: handle did:key → did:web DID transitions, prefer did:web derivation

[beonde]

Summary

SDK-side changes for the did:key → did:web DID upgrade path.

Changes

• DID method transition handling — Agent matching now gracefully handles did:key ↔ did:web transitions (logs at debug level instead of rejecting). This is expected when the server upgrades DID method; agent_id already confirms identity.
• Prefer did:web — When deriving DID from stored keys, prefer did:web:<domain>:agents:<id> over did:key when server URL and agent ID are available.
• Name-based filtering — Agent resolution now filters by name when self.name is specified, preventing mismatches in multi-agent environments.
• Helper — Add _did_method() for clean DID method extraction.

Related PRs

• capiscio-core: feat/jwk-didweb-support (did:web derivation in Go core)
• capiscio-server: feat/jwk-didweb-support (VerifiedLevel cap)"

[github-actions]

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

[github-actions]

✅ SDK server contract tests passed (test_server_integration.py). Cross-product scenarios are validated in capiscio-e2e-tests.

[Copilot]

Pull request overview

Adds SDK-side support for the DID method upgrade path (did:key ↔ did:web) during agent identity recovery and local-key agent resolution, aiming to reduce reconnect friction when the server transitions DID formats.

Changes:

• Introduces _did_method() and uses it to soften DID mismatches caused by DID method transitions during local key→agent matching.
• Updates local key agent resolution to optionally filter by agent name when self.name is provided.
• Adjusts _init_identity() recovery from existing keys to prefer constructing a did:web:<domain>:agents:<agent_id> DID when server_url and agent_id are available.

Comments suppressed due to low confidence (2)

capiscio_sdk/connect.py:616

• Same as above: in the directory-scan path, the mismatch handling will accept any DID-method change (not just did:key ↔ did:web). This broad acceptance can mask real identity mismatches; please constrain the allowed method transitions to the specific upgrade path (key<->web) and continue rejecting other method changes.

                                # did:key ↔ did:web transitions are expected when
                                # server upgrades DID method; agent_id already confirms identity.
                                if _did_method(local_did) != _did_method(server_did):
                                    logger.debug(f"DID method transition for {agent_id}: {local_did} → {server_did}")
                                else:
                                    logger.warning(f"DID mismatch for {agent_id}: local={local_did}, server={server_did}")
                                    continue  # Don't use mismatched agent

capiscio_sdk/connect.py:716

• Deriving did:web from urlparse(self.server_url).netloc can produce an invalid DID when the registry URL includes a port or credentials (e.g. http://localhost:8080 yields did:web:localhost:8080:..., but the port must be percent-encoded as localhost%3A8080). Use urlparse(...).hostname and urlparse(...).port and percent-encode the :<port> when present (or reuse the existing DID helpers that already follow the did:web spec).

                    if self.server_url and self.agent_id:
                        try:
                            from urllib.parse import urlparse
                            domain = urlparse(self.server_url).netloc
                            if domain:
                                did = f"did:web:{domain}:agents:{self.agent_id}"
                        except Exception:

[github-actions]

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

[github-actions]

✅ All checks passed! Ready for review.

[codecov]

Codecov Report

❌ Patch coverage is 89.65517% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
capiscio_sdk/connect.py	89.65%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

✅ SDK server contract tests passed (test_server_integration.py). Cross-product scenarios are validated in capiscio-e2e-tests.

[github-actions]

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

[github-actions]

✅ All checks passed! Ready for review.

[github-actions]

✅ SDK server contract tests passed (test_server_integration.py). Cross-product scenarios are validated in capiscio-e2e-tests.

[github-actions]

✅ Documentation validation passed!

Unified docs will be deployed from capiscio-docs repo.

[github-actions]

✅ All checks passed! Ready for review.

[github-actions]

✅ SDK server contract tests passed (test_server_integration.py). Cross-product scenarios are validated in capiscio-e2e-tests.

[Copilot]

Pull request overview

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