didis-py 0.1.0__tar.gz

didis_py-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,15 @@
+name: CI
+on: { push: { branches: [main] }, pull_request: {} }
+permissions: { contents: read }
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy: { matrix: { python: ["3.11", "3.12", "3.13"] } }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "${{ matrix.python }}" }
+      - run: pip install httpx mypy build
+      - run: mypy --strict didis
+      - run: python -m unittest discover -s tests
+      - run: python -m build

didis_py-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+on:
+  release: { types: [published] }
+permissions: { contents: read }
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install httpx mypy build
+      - run: mypy --strict didis && python -m unittest discover -s tests
+      - name: Tag must match package version
+        run: test "v$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")" = "${GITHUB_REF_NAME}"
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with: { name: dist, path: dist/ }
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions: { id-token: write }   # PyPI trusted publishing; no API token
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - uses: pypa/gh-action-pypi-publish@release/v1

didis_py-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+dist/
+*.egg-info/
+.venv/
+.mypy_cache/

didis_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ledgerbingo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

didis_py-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: didis-py
+Version: 0.1.0
+Summary: Official Python SDK for the DID.is public API: DID resolution with evidence, credentials, policies and agent trust
+Project-URL: Homepage, https://did.is
+Project-URL: Documentation, https://did.is/developers
+Project-URL: Repository, https://github.com/did-is/didis-py
+Project-URL: Issues, https://github.com/did-is/didis-py/issues
+Author: DID.is
+License-Expression: MIT
+License-File: LICENSE
+Keywords: a2a,decentralized-identifiers,did,mcp,resolver,verifiable-credentials,w3c
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Description-Content-Type: text/markdown
+
+# didis-py
+
+Official Python SDK for the [DID.is](https://did.is) public API: DID resolution with evidence, W3C DID Resolution, verifiable credentials, explicit policies, and MCP/A2A agent trust. Sync and async clients on `httpx`; Python 3.11+. Responses are plain `dict`s typed with `TypedDict` (`didis.types`), so editors and mypy know their shape.
+
+The distribution is `didis-py`; the import name is `didis`.
+
+## Install
+
+```bash
+pip install didis-py
+```
+
+## Usage
+
+```python
+from didis import DidisClient, AsyncDidisClient, DidisError
+
+# Defaults to the public API at https://did.is/api; pass base_url when self-hosting.
+with DidisClient() as didis:
+    r = didis.resolve("did:web:identity.foundation")
+    print(r["verdict"]["headline"])
+    for d in r["dimensions"]:
+        print(d["label"], d["state"])
+
+    # DID Resolution v1 (W3C CR Draft HTTPS binding, unmodified)
+    w3c = didis.resolve_w3c("did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK")
+
+    # Live resolution stream (server-sent events)
+    for event, data in didis.stream("did:web:identity.foundation"):
+        if event == "stage":
+            print(data["label"], data["status"])
+
+    # Credentials: VC DM 2.0 / 1.1, Data Integrity (eddsa-jcs-2022, ecdsa-jcs-2019), VC-JOSE/VC-JWT
+    vc = didis.verify_credential(credential)
+    print(vc["status"], vc["headline"])
+
+    # Policies are explicit rules, never scores
+    out = didis.evaluate_policy(
+        "did:web:example.com",
+        {"rules": {"allowedMethods": ["web", "webvh"], "domainBinding": "required"}},
+    )
+    print(out["evaluation"]["status"])
+
+    # Agents
+    mcp = didis.inspect_mcp("https://mcp.example.com/mcp")
+    print(mcp["status"], mcp["inventoryHash"], len(mcp["tools"]))
+    decision = didis.authorize(chain, "payments.refund", trusted_roots=["did:web:example.com"])
+    print(decision["authorization"]["decision"])
+
+    try:
+        didis.resolve("did:web:does-not-exist.invalid")
+    except DidisError as e:
+        print(e.status, e.problem.get("code"), e.problem.get("detail"))
+
+
+async def main() -> None:
+    async with AsyncDidisClient() as didis:
+        diff = await didis.diff("did:web:example.com")
+        print(diff)
+```
+
+Identifiers are percent-encoded exactly once (`quote(did, safe="")`). Non-2xx responses raise `DidisError` with the RFC 9457 problem body.
+
+## Webhooks
+
+Monitoring routes need `admin_token=` and belong on servers only. Verify deliveries with:
+
+```python
+from didis import verify_webhook_signature
+
+ok = verify_webhook_signature(
+    secret,
+    request.headers["x-didis-timestamp"],
+    raw_body,
+    request.headers["x-didis-signature-256"],
+)
+```
+
+Public API reference: <https://did.is/developers>. Monitoring routes need `admin_token=` and are only available on self-hosted deployments; they are not exposed by the public API.
+
+## License
+
+MIT

didis_py-0.1.0/README.md

@@ -0,0 +1,83 @@
+# didis-py
+
+Official Python SDK for the [DID.is](https://did.is) public API: DID resolution with evidence, W3C DID Resolution, verifiable credentials, explicit policies, and MCP/A2A agent trust. Sync and async clients on `httpx`; Python 3.11+. Responses are plain `dict`s typed with `TypedDict` (`didis.types`), so editors and mypy know their shape.
+
+The distribution is `didis-py`; the import name is `didis`.
+
+## Install
+
+```bash
+pip install didis-py
+```
+
+## Usage
+
+```python
+from didis import DidisClient, AsyncDidisClient, DidisError
+
+# Defaults to the public API at https://did.is/api; pass base_url when self-hosting.
+with DidisClient() as didis:
+    r = didis.resolve("did:web:identity.foundation")
+    print(r["verdict"]["headline"])
+    for d in r["dimensions"]:
+        print(d["label"], d["state"])
+
+    # DID Resolution v1 (W3C CR Draft HTTPS binding, unmodified)
+    w3c = didis.resolve_w3c("did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK")
+
+    # Live resolution stream (server-sent events)
+    for event, data in didis.stream("did:web:identity.foundation"):
+        if event == "stage":
+            print(data["label"], data["status"])
+
+    # Credentials: VC DM 2.0 / 1.1, Data Integrity (eddsa-jcs-2022, ecdsa-jcs-2019), VC-JOSE/VC-JWT
+    vc = didis.verify_credential(credential)
+    print(vc["status"], vc["headline"])
+
+    # Policies are explicit rules, never scores
+    out = didis.evaluate_policy(
+        "did:web:example.com",
+        {"rules": {"allowedMethods": ["web", "webvh"], "domainBinding": "required"}},
+    )
+    print(out["evaluation"]["status"])
+
+    # Agents
+    mcp = didis.inspect_mcp("https://mcp.example.com/mcp")
+    print(mcp["status"], mcp["inventoryHash"], len(mcp["tools"]))
+    decision = didis.authorize(chain, "payments.refund", trusted_roots=["did:web:example.com"])
+    print(decision["authorization"]["decision"])
+
+    try:
+        didis.resolve("did:web:does-not-exist.invalid")
+    except DidisError as e:
+        print(e.status, e.problem.get("code"), e.problem.get("detail"))
+
+
+async def main() -> None:
+    async with AsyncDidisClient() as didis:
+        diff = await didis.diff("did:web:example.com")
+        print(diff)
+```
+
+Identifiers are percent-encoded exactly once (`quote(did, safe="")`). Non-2xx responses raise `DidisError` with the RFC 9457 problem body.
+
+## Webhooks
+
+Monitoring routes need `admin_token=` and belong on servers only. Verify deliveries with:
+
+```python
+from didis import verify_webhook_signature
+
+ok = verify_webhook_signature(
+    secret,
+    request.headers["x-didis-timestamp"],
+    raw_body,
+    request.headers["x-didis-signature-256"],
+)
+```
+
+Public API reference: <https://did.is/developers>. Monitoring routes need `admin_token=` and are only available on self-hosted deployments; they are not exposed by the public API.
+
+## License
+
+MIT

didis_py-0.1.0/didis/__init__.py

@@ -0,0 +1,22 @@
+"""DID.is Official Python SDK."""
+
+from . import types
+from .client import (
+    DEFAULT_BASE_URL,
+    AsyncDidisClient,
+    DidisClient,
+    DidisError,
+    verify_customer_monitor_signature,
+    verify_webhook_signature,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DidisClient",
+    "AsyncDidisClient",
+    "DidisError",
+    "types",
+    "verify_webhook_signature",
+    "verify_customer_monitor_signature",
+]
+__version__ = "0.1.0"

didis_py-0.1.0/didis/client.py

@@ -0,0 +1,338 @@
+"""DID.is client SDK for Python (sync and async, httpx).
+
+Identifiers are percent-encoded exactly once; the resolver decodes them exactly once.
+Errors raise ``DidisError`` carrying the RFC 9457 problem object returned by the API.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, AsyncIterator, Dict, Iterator, List, Optional, Tuple, cast
+from urllib.parse import quote
+
+import httpx
+
+from .types import (
+    A2aInspection,
+    AuthorizationResponse,
+    DelegationVerification,
+    DereferencingResult,
+    EnrichedResolution,
+    FastVerifyDidResult,
+    FastVerifyJwsResult,
+    GraphResponse,
+    HealthStatus,
+    HistoryResponse,
+    McpInspection,
+    Policy,
+    PolicyResponse,
+    ResolutionResult,
+    SemanticDiff,
+    ToolAuthorization,
+    CredentialVerification,
+)
+
+DEFAULT_BASE_URL = "https://did.is/api"
+"""Public DID.is API. Pass your own ``base_url`` when self-hosting."""
+
+JSON = Dict[str, Any]
+
+
+def _enc(value: str) -> str:
+    return quote(value.strip(), safe="")
+
+
+class DidisError(Exception):
+    """Raised for non-2xx responses; ``problem`` is the RFC 9457 body."""
+
+    def __init__(self, status: int, problem: JSON):
+        self.status = status
+        self.problem = problem
+        super().__init__(f"{problem.get('title', 'HTTP ' + str(status))}: {problem.get('detail', '')}")
+
+
+def _raise_for_problem(resp: httpx.Response) -> JSON:
+    if resp.is_success:
+        return resp.json() if resp.content else {}
+    try:
+        body = resp.json()
+    except ValueError:
+        body = {"title": f"HTTP {resp.status_code}", "detail": resp.text}
+    problem = body if isinstance(body, dict) else {"detail": str(body)}
+    retry_after = resp.headers.get("retry-after")
+    if retry_after is not None:
+        problem["retryAfter"] = retry_after
+    raise DidisError(resp.status_code, problem)
+
+
+class _SseParser:
+    """Incremental text/event-stream parser yielding (event, json-or-text) per dispatched event."""
+
+    def __init__(self) -> None:
+        self.event = "message"
+        self.data: List[str] = []
+
+    def feed(self, line: str) -> Optional[Tuple[str, Any]]:
+        if line == "":
+            out: Optional[Tuple[str, Any]] = None
+            if self.data:
+                raw = "\n".join(self.data)
+                try:
+                    out = (self.event, json.loads(raw))
+                except ValueError:
+                    out = (self.event, raw)
+            self.event, self.data = "message", []
+            return out
+        if line.startswith("event:"):
+            self.event = line[6:].strip()
+        elif line.startswith("data:"):
+            value = line[5:]
+            self.data.append(value[1:] if value.startswith(" ") else value)
+        return None
+
+
+def verify_webhook_signature(secret: str, timestamp: str, body: bytes, signature_header: str, tolerance_seconds: int = 300) -> bool:
+    """Verifies ``X-Didis-Signature-256 = sha256=HMAC(secret, timestamp + "." + body)``."""
+    try:
+        ts = int(timestamp)
+    except ValueError:
+        return False
+    if abs(time.time() - ts) > tolerance_seconds:
+        return False
+    mac = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(f"sha256={mac}", signature_header)
+
+
+def verify_customer_monitor_signature(secret: str, body: bytes, signature: str, *, tenant_id: str, project_id: str, event_id: str, max_age_seconds: int = 30 * 86400) -> bool:
+    """Verify the durable CUSTOMER event format; receivers MUST durably deduplicate event IDs.
+
+    This creation timestamp is immutable on retry, unlike the existing admin format.
+    A valid signature does not establish DID authority or a paid entitlement.
+    """
+    import re
+    match = re.fullmatch(r"t=(0|[1-9][0-9]{0,15}),v1=([0-9a-f]{64})", signature)
+    if not match or not secret or len(body) > 300 * 1024 or type(max_age_seconds) is not int or not 1 <= max_age_seconds <= 30 * 86400:
+        return False
+    timestamp = int(match[1])
+    now = time.time()
+    if timestamp > 2**53 - 1 or timestamp > now + 60 or now - timestamp >= max_age_seconds:
+        return False
+    mac = hmac.new(secret.encode(), match[1].encode() + b"." + body, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(mac, match[2]):
+        return False
+    try:
+        event = json.loads(body)
+        return (isinstance(event, dict) and event.get("specVersion") == "didis.customer-monitor.v1"
+                and type(event.get("createdAt")) is int and event["createdAt"] == timestamp
+                and re.fullmatch(r"cevent_[0-9a-f]{64}", event_id) is not None and event.get("id") == event_id
+                and re.fullmatch(r"tenant_[0-9a-f]{64}", tenant_id) is not None and event.get("tenantId") == tenant_id
+                and re.fullmatch(r"project_[0-9a-f]{64}", project_id) is not None and event.get("projectId") == project_id)
+    except (ValueError, UnicodeError):
+        return False
+
+
+class DidisClient:
+    """Synchronous client."""
+
+    def __init__(self, base_url: str = DEFAULT_BASE_URL, admin_token: Optional[str] = None, timeout: float = 30.0):
+        self.base_url = base_url.rstrip("/")
+        self._admin_token = admin_token
+        self._client = httpx.Client(base_url=self.base_url, timeout=timeout, headers={"accept": "application/json"})
+
+    def _admin(self) -> Dict[str, str]:
+        if not self._admin_token:
+            raise ValueError("admin_token is required for monitoring routes")
+        return {"authorization": f"Bearer {self._admin_token}"}
+
+    def health(self) -> HealthStatus:
+        return cast(HealthStatus, _raise_for_problem(self._client.get("/health")))
+
+    def resolve(self, did: str, no_cache: bool = False) -> EnrichedResolution:
+        params = {"noCache": "true"} if no_cache else None
+        return cast(EnrichedResolution, _raise_for_problem(self._client.get(f"/v1/resolve/{_enc(did)}", params=params)))
+
+    def resolve_w3c(self, did: str) -> ResolutionResult:
+        return cast(ResolutionResult, _raise_for_problem(self._client.get(f"/1.0/identifiers/{_enc(did)}", headers={"accept": "application/did-resolution"})))
+
+    def dereference(self, did_url: str) -> DereferencingResult:
+        return cast(DereferencingResult, _raise_for_problem(self._client.get(f"/v1/dereference/{_enc(did_url)}")))
+
+    def stream(self, did: str, no_cache: bool = True) -> Iterator[Tuple[str, Any]]:
+        params = {"noCache": "true"} if no_cache else None
+        with self._client.stream("GET", f"/v1/stream/{_enc(did)}", params=params, headers={"accept": "text/event-stream"}) as resp:
+            if not resp.is_success:
+                resp.read()
+                _raise_for_problem(resp)
+            parser = _SseParser()
+            for line in resp.iter_lines():
+                item = parser.feed(line)
+                if item is not None:
+                    yield item
+                    if item[0] == "done":
+                        return
+
+    def history(self, did: str) -> HistoryResponse:
+        return cast(HistoryResponse, _raise_for_problem(self._client.get(f"/v1/history/{_enc(did)}")))
+
+    def diff(self, did: str, from_hash: Optional[str] = None, to_hash: Optional[str] = None) -> SemanticDiff:
+        params = {"from": from_hash, "to": to_hash} if from_hash and to_hash else None
+        return cast(SemanticDiff, _raise_for_problem(self._client.get(f"/v1/diff/{_enc(did)}", params=params)))
+
+    def graph(self, did: str) -> GraphResponse:
+        return cast(GraphResponse, _raise_for_problem(self._client.get(f"/v1/graph/{_enc(did)}")))
+
+    def verify_credential(self, credential: Any, *, expected_audience: Optional[str] = None) -> CredentialVerification:
+        """Check JWT audience only when a recipient is supplied; raw JSON strings preserve member identity."""
+        body: JSON = {"credential": credential}
+        if expected_audience is not None:
+            body["expectedAudience"] = expected_audience
+        return cast(CredentialVerification, _raise_for_problem(self._client.post("/v1/credentials/verify", json=body)))
+
+    def evaluate_policy(self, did: str, policy: Policy, credential: Any = None) -> PolicyResponse:
+        body: JSON = {"did": did, "policy": dict(policy)}
+        if credential is not None:
+            body["credential"] = credential
+        return cast(PolicyResponse, _raise_for_problem(self._client.post("/v1/policies/evaluate", json=body)))
+
+    def inspect_mcp(self, endpoint: str) -> McpInspection:
+        return cast(McpInspection, _raise_for_problem(self._client.get("/v1/mcp/inspect", params={"endpoint": endpoint})))
+
+    def inspect_a2a(self, url: str) -> A2aInspection:
+        return cast(A2aInspection, _raise_for_problem(self._client.get("/v1/a2a/inspect", params={"url": url})))
+
+    def verify_delegation(self, chain: List[str], trusted_roots: Optional[List[str]] = None, register: bool = False) -> DelegationVerification:
+        return cast(DelegationVerification, _raise_for_problem(self._client.post("/v1/agents/verify-delegation", json={"chain": chain, "trustedRoots": trusted_roots, "register": register})))
+
+    def authorize(self, chain: List[str], tool: str, trusted_roots: Optional[List[str]] = None) -> AuthorizationResponse:
+        return cast(AuthorizationResponse, _raise_for_problem(self._client.post("/v1/agents/authorize", json={"chain": chain, "tool": tool, "trustedRoots": trusted_roots})))
+
+    def verify_tool(self, agent: str, tool: str, root: Optional[str] = None) -> ToolAuthorization:
+        params = {"agent": agent, "tool": tool, **({"root": root} if root else {})}
+        return cast(ToolAuthorization, _raise_for_problem(self._client.get("/v1/agents/verify-tool", params=params)))
+
+    def fast_verify_did(self, did: str) -> FastVerifyDidResult:
+        return cast(FastVerifyDidResult, _raise_for_problem(self._client.get(f"/v1/fast-verify/did/{_enc(did)}")))
+
+    def fast_verify_jws(self, jws: str, relationship: Optional[str] = None) -> FastVerifyJwsResult:
+        return cast(FastVerifyJwsResult, _raise_for_problem(self._client.post("/v1/fast-verify/jws", json={"jws": jws, "relationship": relationship})))
+
+    # Monitoring (admin token required)
+    def watch(self, did: str, webhook_url: str, interval_seconds: Optional[int] = None) -> JSON:
+        return _raise_for_problem(self._client.post("/v1/monitoring/watches", json={"did": did, "webhookUrl": webhook_url, "intervalSeconds": interval_seconds}, headers=self._admin()))
+
+    def watches(self) -> JSON:
+        return _raise_for_problem(self._client.get("/v1/monitoring/watches", headers=self._admin()))
+
+    def unwatch(self, watch_id: str) -> None:
+        _raise_for_problem(self._client.delete(f"/v1/monitoring/watches/{_enc(watch_id)}", headers=self._admin()))
+
+    def events(self, watch_id: Optional[str] = None) -> JSON:
+        params = {"watchId": watch_id} if watch_id else None
+        return _raise_for_problem(self._client.get("/v1/monitoring/events", params=params, headers=self._admin()))
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "DidisClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncDidisClient:
+    """Asynchronous client (same surface as ``DidisClient``)."""
+
+    def __init__(self, base_url: str = DEFAULT_BASE_URL, admin_token: Optional[str] = None, timeout: float = 30.0):
+        self.base_url = base_url.rstrip("/")
+        self._admin_token = admin_token
+        self._client = httpx.AsyncClient(base_url=self.base_url, timeout=timeout, headers={"accept": "application/json"})
+
+    def _admin(self) -> Dict[str, str]:
+        if not self._admin_token:
+            raise ValueError("admin_token is required for monitoring routes")
+        return {"authorization": f"Bearer {self._admin_token}"}
+
+    async def health(self) -> HealthStatus:
+        return cast(HealthStatus, _raise_for_problem(await self._client.get("/health")))
+
+    async def resolve(self, did: str, no_cache: bool = False) -> EnrichedResolution:
+        params = {"noCache": "true"} if no_cache else None
+        return cast(EnrichedResolution, _raise_for_problem(await self._client.get(f"/v1/resolve/{_enc(did)}", params=params)))
+
+    async def resolve_w3c(self, did: str) -> ResolutionResult:
+        return cast(ResolutionResult, _raise_for_problem(await self._client.get(f"/1.0/identifiers/{_enc(did)}", headers={"accept": "application/did-resolution"})))
+
+    async def dereference(self, did_url: str) -> DereferencingResult:
+        return cast(DereferencingResult, _raise_for_problem(await self._client.get(f"/v1/dereference/{_enc(did_url)}")))
+
+    async def stream(self, did: str, no_cache: bool = True) -> AsyncIterator[Tuple[str, Any]]:
+        params = {"noCache": "true"} if no_cache else None
+        async with self._client.stream("GET", f"/v1/stream/{_enc(did)}", params=params, headers={"accept": "text/event-stream"}) as resp:
+            if not resp.is_success:
+                await resp.aread()
+                _raise_for_problem(resp)
+            parser = _SseParser()
+            async for line in resp.aiter_lines():
+                item = parser.feed(line)
+                if item is not None:
+                    yield item
+                    if item[0] == "done":
+                        return
+
+    async def history(self, did: str) -> HistoryResponse:
+        return cast(HistoryResponse, _raise_for_problem(await self._client.get(f"/v1/history/{_enc(did)}")))
+
+    async def diff(self, did: str, from_hash: Optional[str] = None, to_hash: Optional[str] = None) -> SemanticDiff:
+        params = {"from": from_hash, "to": to_hash} if from_hash and to_hash else None
+        return cast(SemanticDiff, _raise_for_problem(await self._client.get(f"/v1/diff/{_enc(did)}", params=params)))
+
+    async def graph(self, did: str) -> GraphResponse:
+        return cast(GraphResponse, _raise_for_problem(await self._client.get(f"/v1/graph/{_enc(did)}")))
+
+    async def verify_credential(self, credential: Any, *, expected_audience: Optional[str] = None) -> CredentialVerification:
+        """Check JWT audience only when a recipient is supplied; raw JSON strings preserve member identity."""
+        body: JSON = {"credential": credential}
+        if expected_audience is not None:
+            body["expectedAudience"] = expected_audience
+        return cast(CredentialVerification, _raise_for_problem(await self._client.post("/v1/credentials/verify", json=body)))
+
+    async def evaluate_policy(self, did: str, policy: Policy, credential: Any = None) -> PolicyResponse:
+        body: JSON = {"did": did, "policy": dict(policy)}
+        if credential is not None:
+            body["credential"] = credential
+        return cast(PolicyResponse, _raise_for_problem(await self._client.post("/v1/policies/evaluate", json=body)))
+
+    async def inspect_mcp(self, endpoint: str) -> McpInspection:
+        return cast(McpInspection, _raise_for_problem(await self._client.get("/v1/mcp/inspect", params={"endpoint": endpoint})))
+
+    async def inspect_a2a(self, url: str) -> A2aInspection:
+        return cast(A2aInspection, _raise_for_problem(await self._client.get("/v1/a2a/inspect", params={"url": url})))
+
+    async def verify_delegation(self, chain: List[str], trusted_roots: Optional[List[str]] = None, register: bool = False) -> DelegationVerification:
+        return cast(DelegationVerification, _raise_for_problem(await self._client.post("/v1/agents/verify-delegation", json={"chain": chain, "trustedRoots": trusted_roots, "register": register})))
+
+    async def authorize(self, chain: List[str], tool: str, trusted_roots: Optional[List[str]] = None) -> AuthorizationResponse:
+        return cast(AuthorizationResponse, _raise_for_problem(await self._client.post("/v1/agents/authorize", json={"chain": chain, "tool": tool, "trustedRoots": trusted_roots})))
+
+    async def verify_tool(self, agent: str, tool: str, root: Optional[str] = None) -> ToolAuthorization:
+        params = {"agent": agent, "tool": tool, **({"root": root} if root else {})}
+        return cast(ToolAuthorization, _raise_for_problem(await self._client.get("/v1/agents/verify-tool", params=params)))
+
+    async def fast_verify_did(self, did: str) -> FastVerifyDidResult:
+        return cast(FastVerifyDidResult, _raise_for_problem(await self._client.get(f"/v1/fast-verify/did/{_enc(did)}")))
+
+    async def fast_verify_jws(self, jws: str, relationship: Optional[str] = None) -> FastVerifyJwsResult:
+        return cast(FastVerifyJwsResult, _raise_for_problem(await self._client.post("/v1/fast-verify/jws", json={"jws": jws, "relationship": relationship})))
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncDidisClient":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()

didis_py-0.1.0/didis/types.py

@@ -0,0 +1,414 @@
+"""Wire types for the DID.is public API (camelCase JSON, returned as plain ``dict``).
+
+These are ``TypedDict`` declarations: they give editors and type checkers the response shape
+without changing runtime behaviour. Fields marked ``NotRequired`` may be absent. String states
+are typed as ``str`` because the server may add new states in a minor release.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, NotRequired, Optional, Tuple, TypedDict
+
+DimensionState = Literal["ESTABLISHED", "SELF_CERTIFYING", "NOT_ESTABLISHED", "FAILED", "INDETERMINATE", "NOT_APPLICABLE"]
+
+
+class TraceStage(TypedDict):
+    stage: str
+    label: str
+    status: str
+    startedUs: int
+    durationUs: int
+    detail: str
+
+
+class Problem(TypedDict, total=False):
+    type: str
+    title: str
+    status: int
+    detail: str
+    code: str
+    trace: List[TraceStage]
+    retryAfter: str
+
+
+class Check(TypedDict):
+    id: str
+    label: str
+    status: str
+    detail: str
+
+
+class EvidenceDimension(TypedDict):
+    id: str
+    label: str
+    state: DimensionState
+    statement: str
+    proves: str
+    doesNotProve: str
+
+
+class Verdict(TypedDict):
+    outcome: str
+    headline: str
+    statements: List[str]
+
+
+class KeyEvidence(TypedDict):
+    id: str
+    type: str
+    controller: NotRequired[str]
+    controllerIsSubject: bool
+    relationships: List[str]
+    status: str
+    curve: NotRequired[str]
+    keySizeBits: NotRequired[int]
+    jwkThumbprint: NotRequired[str]
+    multikey: NotRequired[str]
+    jwk: NotRequired[Dict[str, Any]]
+    detail: str
+
+
+class DomainBindingEvidence(TypedDict):
+    status: str
+    origin: str
+    configurationUrl: str
+    linkedDids: List[str]
+    credentials: List[Dict[str, Any]]
+    detail: str
+
+
+class Evidence(TypedDict):
+    source: Dict[str, Any]
+    document: Dict[str, Any]
+    keys: List[KeyEvidence]
+    services: List[Dict[str, Any]]
+    domainBinding: NotRequired[DomainBindingEvidence]
+    tls: NotRequired[Dict[str, Any]]
+    history: NotRequired[Dict[str, Any]]
+
+
+class GraphNode(TypedDict):
+    id: str
+    kind: str
+    label: str
+    sublabel: NotRequired[str]
+    state: str
+    layer: int
+    digest: NotRequired[str]
+    facts: List[Tuple[str, str]]
+
+
+# ``from`` is a Python keyword, so this TypedDict uses the functional form.
+GraphEdge = TypedDict("GraphEdge", {"id": str, "from": str, "to": str, "relation": str, "state": str})
+
+
+class Graph(TypedDict):
+    nodes: List[GraphNode]
+    edges: List[GraphEdge]
+
+
+class EnrichedResolution(TypedDict):
+    did: str
+    method: str
+    didDocument: Optional[Dict[str, Any]]
+    didResolutionMetadata: Dict[str, Any]
+    didDocumentMetadata: Dict[str, Any]
+    verdict: Verdict
+    dimensions: List[EvidenceDimension]
+    evidence: Evidence
+    graph: Graph
+    trace: List[TraceStage]
+    limitations: List[str]
+    resolver: Dict[str, str]
+    observedAt: str
+    cached: bool
+
+
+ResolutionResult = TypedDict(
+    "ResolutionResult",
+    {"@context": str, "didDocument": Optional[Dict[str, Any]], "didResolutionMetadata": Dict[str, Any], "didDocumentMetadata": Dict[str, Any]},
+)
+
+DereferencingResult = TypedDict(
+    "DereferencingResult",
+    {"@context": str, "dereferencingMetadata": Dict[str, Any], "contentStream": Any, "contentMetadata": Dict[str, Any]},
+)
+
+
+class HealthStatus(TypedDict):
+    status: str
+    name: str
+    version: str
+    time: str
+    supportedMethods: List[str]
+    standards: Dict[str, Any]
+    monitoring: NotRequired[bool]
+    rateLimited: NotRequired[bool]
+
+
+class ObservationRecord(TypedDict):
+    id: int
+    did: str
+    documentHash: str
+    observedAt: str
+    lastSeenAt: str
+    seenCount: int
+    latencyMs: int
+    resolverVersion: str
+    domainBindingStatus: str
+    summary: Optional[Dict[str, Any]]
+
+
+class HistoryResponse(TypedDict):
+    did: str
+    count: int
+    history: List[ObservationRecord]
+    note: str
+
+
+class RelationshipChange(TypedDict):
+    relationship: str
+    added: List[str]
+    removed: List[str]
+
+
+class SemanticDiff(TypedDict):
+    did: str
+    fromHash: str
+    toHash: str
+    fromObservedAt: str
+    toObservedAt: str
+    identical: bool
+    keysAdded: List[str]
+    keysRemoved: List[str]
+    keysRotated: List[str]
+    relationshipsChanged: List[RelationshipChange]
+    servicesAdded: List[str]
+    servicesRemoved: List[str]
+    servicesChanged: List[str]
+    controllerChanged: bool
+    alsoKnownAsChanged: bool
+    contextsChanged: bool
+    domainBindingFrom: str
+    domainBindingTo: str
+    domainBindingChanged: bool
+    changedMembers: List[str]
+    summary: List[str]
+    fromDocument: Any
+    toDocument: Any
+
+
+class GraphResponse(TypedDict):
+    did: str
+    observedAt: str
+    verdict: Verdict
+    nodes: List[GraphNode]
+    edges: List[GraphEdge]
+
+
+class CredentialVerification(TypedDict):
+    status: str
+    headline: str
+    format: str
+    dataModel: str
+    id: NotRequired[str]
+    issuer: NotRequired[str]
+    issuerName: NotRequired[str]
+    subject: NotRequired[str]
+    types: List[str]
+    validFrom: NotRequired[str]
+    validUntil: NotRequired[str]
+    checks: List[Check]
+    proof: NotRequired[Dict[str, Any]]
+    statusList: List[Dict[str, Any]]
+    issuerResolution: NotRequired[Dict[str, Any]]
+    claims: Any
+    credential: Any
+    limitations: List[str]
+    valid: bool
+    errors: List[str]
+
+
+class PolicyRules(TypedDict, total=False):
+    didResolution: Literal["required", "optional"]
+    allowedMethods: List[str]
+    allowedCurves: List[str]
+    allowedKeySuites: List[str]
+    minKeyBits: int
+    requireKeyRelationship: str
+    domainBinding: Literal["required", "optional"]
+    tlsMinDaysRemaining: int
+    verifiableHistory: Literal["required"]
+    maxCacheAgeSeconds: int
+    credentialStatus: Literal["active"]
+    credentialIssuerMustBeSubject: bool
+
+
+class Policy(TypedDict):
+    name: NotRequired[str]
+    rules: PolicyRules
+
+
+class PolicyRuleEvaluation(TypedDict):
+    rule: str
+    status: str
+    message: str
+    expected: NotRequired[Any]
+    observedValue: NotRequired[Any]
+
+
+class PolicyEvaluation(TypedDict):
+    did: str
+    policyName: NotRequired[str]
+    status: Literal["PASS", "FAIL", "INDETERMINATE", "NOT_APPLICABLE"]
+    headline: str
+    rulesEvaluated: int
+    rulesPassed: int
+    evaluations: List[PolicyRuleEvaluation]
+    evaluatedAt: str
+
+
+class PolicyResponse(TypedDict):
+    evaluation: PolicyEvaluation
+    credential: Optional[CredentialVerification]
+    resolution: Optional[Dict[str, Any]]
+
+
+class ToolEvidence(TypedDict):
+    name: str
+    title: NotRequired[str]
+    description: str
+    definitionSha256: str
+    schemaSha256: str
+    parameters: List[str]
+    annotations: Any
+    declaredClass: NotRequired[str]
+    heuristicClass: str
+    riskSignals: List[str]
+    drift: str
+    inputSchema: Any
+
+
+class McpInspection(TypedDict):
+    endpoint: str
+    status: str
+    mode: str
+    negotiatedVersion: NotRequired[str]
+    supportedVersions: List[str]
+    serverInfo: Optional[Dict[str, Any]]
+    capabilities: Any
+    instructions: NotRequired[str]
+    tools: List[ToolEvidence]
+    inventoryHash: str
+    jcsProfile: NotRequired[str]
+    classCounts: Dict[str, int]
+    drift: Dict[str, Any]
+    auth: NotRequired[Dict[str, Any]]
+    transcript: List[Dict[str, Any]]
+    checks: List[Check]
+    headline: str
+    tls: NotRequired[Dict[str, Any]]
+    limitations: List[str]
+
+
+class A2aInspection(TypedDict):
+    cardUrl: str
+    httpStatus: int
+    cardSha256: str
+    canonicalSha256: str
+    jcsProfile: NotRequired[str]
+    specVersion: str
+    name: str
+    description: str
+    version: NotRequired[str]
+    provider: NotRequired[Dict[str, Any]]
+    documentationUrl: NotRequired[str]
+    interfaces: List[Dict[str, Any]]
+    capabilities: Optional[Dict[str, Any]]
+    securitySchemes: List[Dict[str, Any]]
+    skills: List[Dict[str, Any]]
+    signatures: List[Dict[str, Any]]
+    checks: List[Check]
+    headline: str
+    card: Any
+    tls: NotRequired[Dict[str, Any]]
+    limitations: List[str]
+
+
+class DelegationLink(TypedDict):
+    index: int
+    issuer: str
+    audience: str
+    capabilities: List[str]
+    notBefore: NotRequired[str]
+    expires: NotRequired[str]
+    jti: NotRequired[str]
+    kid: NotRequired[str]
+    alg: NotRequired[str]
+    digest: str
+    signatureValid: bool
+    status: str
+    issuerHeadline: NotRequired[str]
+    checks: List[Check]
+
+
+class DelegationChainResult(TypedDict):
+    status: str
+    headline: str
+    format: str
+    root: NotRequired[str]
+    leaf: NotRequired[str]
+    effectiveCapabilities: List[str]
+    notAfter: NotRequired[str]
+    trustedRoot: NotRequired[bool]
+    links: List[DelegationLink]
+    checks: List[Check]
+    limitations: List[str]
+
+
+class DelegationVerification(TypedDict):
+    result: DelegationChainResult
+    registered: bool
+
+
+class ToolAuthorization(TypedDict):
+    agent: str
+    tool: str
+    decision: Literal["ALLOW", "DENY"]
+    authorized: bool
+    reason: str
+    matchedCapability: NotRequired[str]
+    root: NotRequired[str]
+    expires: NotRequired[str]
+
+
+class AuthorizationResponse(TypedDict):
+    authorization: ToolAuthorization
+    chain: DelegationChainResult
+
+
+class FastVerifyDidResult(TypedDict):
+    did: str
+    resolved: bool
+    outcome: str
+    headline: str
+    statements: List[str]
+    dimensions: List[Dict[str, str]]
+    keys: List[Dict[str, Any]]
+    domainBinding: Optional[str]
+    documentSha256: NotRequired[str]
+    observedAt: str
+    cached: bool
+
+
+class FastVerifyJwsResult(TypedDict):
+    status: Literal["VALID", "INVALID", "INDETERMINATE", "UNSUPPORTED", "MALFORMED"]
+    valid: bool
+    headline: str
+    alg: NotRequired[str]
+    kid: NotRequired[str]
+    typ: NotRequired[str]
+    payload: NotRequired[Any]
+    signingInputSha256: NotRequired[str]
+    signer: NotRequired[str]
+    relationship: NotRequired[str]

didis_py-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+# The import package directory is `didis`, which differs from the distribution name `didis-py`,
+# so it must be declared explicitly for hatchling to locate it.
+packages = ["didis"]
+
+[project]
+name = "didis-py"
+version = "0.1.0"
+description = "Official Python SDK for the DID.is public API: DID resolution with evidence, credentials, policies and agent trust"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "DID.is" }
+]
+dependencies = [
+    "httpx>=0.27.0",
+]
+keywords = ["did", "w3c", "decentralized-identifiers", "verifiable-credentials", "mcp", "a2a", "resolver"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://did.is"
+Documentation = "https://did.is/developers"
+Repository = "https://github.com/did-is/didis-py"
+Issues = "https://github.com/did-is/didis-py/issues"

didis_py-0.1.0/tests/test_credential_contract.py

@@ -0,0 +1,53 @@
+"""Sync/async credential audience options preserve raw text and error retry metadata."""
+import json
+import unittest
+from unittest.mock import patch
+
+import httpx
+from didis.client import AsyncDidisClient, DidisClient, DidisError
+
+RAW = '{"issuer":"bad","issuer":"good"}'
+
+
+def transport_handler(request: httpx.Request) -> httpx.Response:
+    assert request.url.path == "/v1/credentials/verify"
+    body = json.loads(request.content)
+    assert body["credential"] == RAW
+    if body.get("expectedAudience") == "recipient":
+        return httpx.Response(429, json={"title": "Limited", "detail": "Retry later"}, headers={"retry-after": "5"})
+    assert "expectedAudience" not in body
+    return httpx.Response(200, json={"status": "MALFORMED", "valid": False})
+
+
+class SyncContract(unittest.TestCase):
+    def test_additive_audience_raw_text_and_retry_hint(self) -> None:
+        underlying = httpx.Client(base_url="https://example.com", transport=httpx.MockTransport(transport_handler))
+        with patch("didis.client.httpx.Client", return_value=underlying):
+            client = DidisClient("https://example.com")
+        try:
+            self.assertEqual(client.verify_credential(RAW)["status"], "MALFORMED")
+            with self.assertRaises(DidisError) as caught:
+                client.verify_credential(RAW, expected_audience="recipient")
+            self.assertEqual(caught.exception.status, 429)
+            self.assertEqual(caught.exception.problem["retryAfter"], "5")
+        finally:
+            client.close()
+
+
+class AsyncContract(unittest.IsolatedAsyncioTestCase):
+    async def test_additive_audience_raw_text_and_retry_hint(self) -> None:
+        underlying = httpx.AsyncClient(base_url="https://example.com", transport=httpx.MockTransport(transport_handler))
+        with patch("didis.client.httpx.AsyncClient", return_value=underlying):
+            client = AsyncDidisClient("https://example.com")
+        try:
+            self.assertEqual((await client.verify_credential(RAW))["status"], "MALFORMED")
+            with self.assertRaises(DidisError) as caught:
+                await client.verify_credential(RAW, expected_audience="recipient")
+            self.assertEqual(caught.exception.status, 429)
+            self.assertEqual(caught.exception.problem["retryAfter"], "5")
+        finally:
+            await client.close()
+
+
+if __name__ == "__main__":
+    unittest.main()

didis_py-0.1.0/tests/test_customer_webhook_signature.py

@@ -0,0 +1,45 @@
+"""Independent Python receiver verification, no provider or network access."""
+import hashlib
+import hmac
+import json
+import time
+import unittest
+from didis import verify_customer_monitor_signature
+
+
+class CustomerSignatureTests(unittest.TestCase):
+    def setUp(self):
+        self.now = int(time.time())
+        self.secret = "synthetic-python-customer-webhook-secret"
+        self.scope = dict(tenant_id="tenant_" + "a" * 64, project_id="project_" + "b" * 64, event_id="cevent_" + "c" * 64)
+
+    def sample(self, timestamp=None):
+        timestamp = self.now if timestamp is None else timestamp
+        body = json.dumps(dict(specVersion="didis.customer-monitor.v1", id=self.scope["event_id"], tenantId=self.scope["tenant_id"], projectId=self.scope["project_id"], createdAt=timestamp, data={"note": "€ 😀"}), ensure_ascii=False).encode()
+        signature = f"t={timestamp},v1={hmac.new(self.secret.encode(), str(timestamp).encode() + b'.' + body, hashlib.sha256).hexdigest()}"
+        return body, signature
+
+    def test_exact_raw_body_and_explicit_owner_scope(self):
+        body, signature = self.sample()
+        self.assertTrue(verify_customer_monitor_signature(self.secret, body, signature, **self.scope))
+        self.assertFalse(verify_customer_monitor_signature(self.secret, body + b" ", signature, **self.scope))
+        wrong = dict(self.scope, project_id="project_" + "d" * 64)
+        self.assertFalse(verify_customer_monitor_signature(self.secret, body, signature, **wrong))
+
+    def test_immutable_retry_time_not_admin_five_minute_tolerance(self):
+        body, signature = self.sample(self.now - 3600)
+        self.assertTrue(verify_customer_monitor_signature(self.secret, body, signature, **self.scope))
+        for ts in [self.now - 30 * 86400, self.now + 120]:
+            body, signature = self.sample(ts)
+            self.assertFalse(verify_customer_monitor_signature(self.secret, body, signature, **self.scope))
+
+    def test_malformed_header_and_invalid_limits_are_refused(self):
+        body, signature = self.sample()
+        for header in [signature + ",v1=other", "t=0,v1=short", "", signature.replace("t=", "t=0")]:
+            self.assertFalse(verify_customer_monitor_signature(self.secret, body, header, **self.scope))
+        for age in [0, -1, 2592001, True]:
+            self.assertFalse(verify_customer_monitor_signature(self.secret, body, signature, max_age_seconds=age, **self.scope))
+
+
+if __name__ == "__main__":
+    unittest.main()