proof-holdings-sdk 1.1.0__tar.gz

proof_holdings_sdk-1.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+._*

proof_holdings_sdk-1.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+Notable changes to [`proof-holdings-sdk`](https://pypi.org/project/proof-holdings-sdk/) (import name
+`proof_sdk`). Source: [ProofHoldings/sdk-python](https://github.com/ProofHoldings/sdk-python).
+
+## 1.1.0 — 2026-10-14
+
+The first release on PyPI.
+
+### Added
+
+- `Proof()` without a key resolves one: a non-empty `PROOF_API_KEY`, else the entry that
+  `npx @proof-holdings/mcp-server login` saved in `~/.proof-holdings/credentials` for the client's base
+  URL. The base URL is the `base_url` argument, else `PROOF_BASE_URL`, else
+  `https://api.proof.holdings`. An explicit key behaves as before; an explicit empty key is an error.
+- `verifications.delete_domain_verification(id)` deletes a domain verification attempt that is not
+  verified (pending, verifying or failed). A verified domain is refused with 409 `domain_verified`.
+- Types for account deletion and export, identifier, domain and project removal, the artifact claim
+  lookup, and the Delegations section of a public profile.
+- API-key listings carry `replaced_key_ids`: a key's usage covers every key it replaced.
+- The `free` billing plan in `BillingPlan`.

proof_holdings_sdk-1.1.0/CLAUDE.md

@@ -0,0 +1,40 @@
+# Python SDK CLAUDE.md
+
+## Purpose
+Official Python client SDK for the proof.holdings REST API. PyPI distribution `proof-holdings-sdk`; the import package stays `proof_sdk` under `src/`, and because the two names differ, `pyproject.toml`'s wheel target names `src/proof_sdk` explicitly.
+
+## Narrative Summary
+The client (`client.py`) wires 17 resources: verifications, verification_requests, proofs, sessions, streams, webhook_deliveries, authorizations, confirmations, hitl, hitl_keys, templates, profiles, public_profiles, me, proof_me, circles, delegations. **api-map rule**: a module counts toward `available` only once it is BOTH re-exported from `resources/__init__.py` AND instantiated as `Class(self._http)` in `client.py` — keyword arguments after `self._http` are allowed (`Proofs(self._http, max_jwks_age=...)`), and both parsers of `client.py` accept them: `getWiredPyResources` in `scripts/api-map-shared.ts` and `readPyClient` in `src/__tests__/drift/sdk-code-samples.test.ts`. **Construction**: `Proof(api_key: str | None = None, *, base_url: str | None = None, …)` — an omitted key and the base URL resolve through `proof_sdk/credentials.py` (stdlib only, so `test_packaging.py` sees nothing new; the cross-SDK contract is in `../CLAUDE.md`): `resolve_api_key`, `resolve_base_url`, `credential_key`, `default_credentials_path`, `read_credentials_file`, `missing_key_message`, the frozen dataclass `ResolvedKey`, `CredentialsFileError`, `LOGIN_COMMAND` and `DEFAULT_BASE_URL` (which `client.py` re-exports, having been its home before). `__init__.py` exports `resolve_api_key`, `resolve_base_url`, `ResolvedKey`, `LOGIN_COMMAND`. The HTTP layer (`http.py`) exposes `request`/`get`/`post`/`put`/`delete` (`delete` accepts a `json=` body). `AsyncClient` is built with `follow_redirects=True` so the avatar 301 is followed; non-JSON 2xx returns a `{"data": bytes, "content_type": str}` envelope (see `../CLAUDE.md`).
+
+- `hitl` — config CRUD (`create`/`list`/`retrieve`/`update`/`archive`/`finalize`/`request_authorization`/`create_chat_id_discovery`/`get_approver_keys`).
+- `templates` (7 → `/templates*`), `profiles` (10 incl. profile-template CRUD → `/me/profiles*`), `public_profiles` (`get_by_id`/`get_avatar`/`get_by_username`/`get_badge`/`check_username`, unauthenticated; `get_by_id` takes the PUBLIC `profile_id` only; `get_avatar` returns `{"data": bytes, "content_type": str}`; `get_badge(username)` returns the embed descriptor — branch on its `state`, since a username with no public record answers 200, never 404).
+- `me` (class `Me`) — the dual-auth data surface `summary`/`search`/`api_key_self`/`api_key_usage`.
+- `verifications` — also multi-channel (`create_multi_channel`/`get_multi_channel_status`; returns the generated `MultiChannel*` TypedDicts). Test-mode groups have no completion path (`unsupported_for_group`).
+- `delegations` (class `Delegations`) — Proof of Delegation (`create`/`list`/`retrieve`/`revoke` → `/api/v1/delegations*`). Return annotations use the generated aliases from `types.py`, and since `m-fix-delegation-list-cascade` flattened the four delegation OpenAPI schemas off a shared shape, ALL of them are real TypedDicts — `DelegationWithToken`/`DelegationDetail` had been literal `Any` for as long as they existed (allOf compositions degrade to `Any` in the Python type generator), so the detail shipped untyped until then. `DelegationListResponse.data` is `list[DelegationListItem]` — `Delegation` plus the derived `effective_status`/`is_valid`; the `status` kwarg filters the delegation's own stored record, not the derived one. Since `m-fix-proof-api-consistency` the writes carry the derived pair too, so `create` is annotated `DelegationDetail` and `revoke` `DelegationListItem` (previously `DelegationWithToken` / `Delegation`).
+- `proof_me` (class `ProofMe`) — the Proof-Me surface (2 async methods: `create_identity_challenge`/`get_identity_challenge`; returns the generated `IdentityChallengeResponse` from `types.py`). Challenger enrollment lives on the `circles` resource.
+- `circles` (class `Circles`) — Circle people-primitive: CRUD + member management + member-channel management (13 methods). Response types (`Circle`, `CircleListResponse`, `CircleMember`, `CircleMemberChannel`, `CircleMemberChannelListResponse`, `CircleMemberDrillResponse`, `CircleMemberInviteResponse`, `CircleMemberListResponse`) are imported from the generated `types.py`; the resource module no longer declares them as inline `TypedDict`s (unified 2026-09, `m-sdk-proofme-circle-reshape` — the two had drifted into a field-for-field duplicate).
+
+**⚠️ Parser constraints (load-bearing) — `parsePySdkMethods` in `scripts/api-map-shared.ts`:**
+- The PATCH verb MUST stay on the SAME LINE as `self._http.request(` — the same-line regex only recognizes `self._http.request("VERB", ...)` when `"VERB"` is on the opening line; breaking it across lines silently DROPS the endpoint from the `available` claim (affects `hitl.update`, `profiles.update`).
+- Multi-segment path f-strings (e.g. `profiles.update_template`/`delete_template`) MUST stay on ONE line — the parser doesn't join adjacent string literals across lines.
+
+The multi-channel status f-string uses `{quote(group_id, safe='')}` with SINGLE quotes — nesting `safe=""` in a double-quoted f-string is PEP 701 (3.12+) while `requires-python` is `>=3.10` (several pre-existing methods already violate this — a known follow-up).
+
+- **Streaming** (`streaming.py`, `resources/streams.py`) — every stream is an async generator yielding `{"event", "id", "data"}` dicts like the other SDKs (`_parse_sse_block` keeps the `event:`/`id:` fields; `data` is JSON-decoded, or the raw text when not JSON); the polling fallback yields `poll` events and a terminal snapshot as `terminal`. `cancel_event` is RACED against each socket read (`_until_cancelled`), so a set event stops the generator promptly even while the server is silent between its 30s keepalives, raising `asyncio.CancelledError`. The asset stream's fallback polls `…/assets/{idx}/status`, ends on `verified`/`failed`/`expired`/`revoked`, and — through `request_terminal_states` — on a request `cancelled`/`expired` (cross-SDK contract in `../CLAUDE.md`). Tests: `tests/test_streaming.py`.
+- `proofs` (class `Proofs`) — `verify_offline(token, *, check_revocation=True)` reads the token's status-list slot by default and enforces the key-rotation rules (contract in `../CLAUDE.md`); `refresh_jwks()` forces a refetch, `clear_tombstones()` resets tombstones, `Proof(max_jwks_age=...)` (seconds, validated by `validate_max_jwks_age` when `Proofs` is constructed) bounds a stale key set. Python-specific:
+  - `proof_sdk/jwks/keyset.py` ports the verifier's `packages/delegation-verifier/src/keyset.ts` function for function (state persistence omitted — the key set is in memory only); a rule change lands in the verifier first. `proof_sdk/jwks/key_set_cache.py` is the I/O shell (`KeySetCache`: TTL, cooldowns, confirmed-only fallback, staleness; single-flight is one asyncio Task awaited through `asyncio.shield`, so a cancelled waiter does not cancel the shared fetch). Test seams `set_jwks_clock_for_tests` / `set_jwks_event_listener_for_tests`; a tombstone naming a live key is logged as a warning on the `proof_sdk` logger.
+  - PyJWT only imports keys (`jwt.PyJWK`) and checks signatures (`jwt.PyJWS().decode` per candidate). The claims are checked by `_claims_failure` in `resources/proofs.py` on the SDK's clock, which PyJWT cannot take: `exp`/`iat`/`nbf` must be finite numbers when present (a NumericDate must be a JSON number — PyJWT coerced numeric strings), `sub`/`jti` strings when present, and on the token path (not the status list) `iss` must match and a non-empty `aud` is refused (no audience is asked for).
+  - The key set and the status list both go through `http.fetch_public`, a second credential-free `AsyncClient` (`follow_redirects=False`, branded UA) that STREAMS via `client.stream` under one `asyncio.wait_for` over the whole transfer — httpx's own timeout bounds each socket operation and the read loop would restart it on every chunk — and abandons the body one byte past `max_bytes` (512 KiB). `verify_offline` answers a result dict on an unexpected error during checking rather than raising (it still raises `ImportError` without PyJWT), and `_origin` is wrapped where it is called: `urlsplit(...).port` RAISES for a port outside 0-65535 and `urlsplit` for a malformed IPv6 literal, which made this the only SDK that raised instead of failing closed.
+
+## Key Files
+- `src/proof_sdk/` (package root), `pyproject.toml`, `pytest.ini`, `tests/conftest.py`.
+
+## Test Layout
+- **Unit** (`tests/test_*.py`) via `pytest --ignore=tests/integration` (what `python-sdk-tests` runs on PRs after `pip install -e '.[jwt]'`; `pytest.ini` sets no `testpaths`, so a bare `pytest` also collects the integration suite). `test_resources.py` covers templates/profiles/public_profiles; `test_http.py` covers the `{data, content_type}` envelope + the `follow_redirects` assertion; `test_packaging.py` is a packaging drift guard — every top-level third-party import in `src/proof_sdk` must be covered by a declared `[project]` dependency in `pyproject.toml` (runtime deps: `httpx`, `typing-extensions`, `cryptography` — the last because `proof_sdk.crypto.hitl_crypto` imports it at module top and a confirmation cannot be created without `encrypt_message`, so a bare `pip install proof-holdings-sdk` must carry it; only `jwt`, the offline-verification extra imported lazily in `proofs.py` and `jwks/key_set_cache.py`, is exempt). `test_offline_revocation.py` runs against a real loopback HTTP server; `test_jwks_rotation_fixtures.py` runs the shared rotation cases through an `httpx.MockTransport` patched into the SDK's `AsyncClient`. `test_credentials_fixtures.py` runs the shared credentials cases through `Proof()` with `HOME` monkeypatched to `tmp_path`; the `AsyncClient` it swaps in must be built with the SDK's `base_url` and headers (the key read back from `proof._http._api_key`), as `tests/integration/conftest.py` does, because `http.py` puts both on the client and `request()` passes none per request.
+- **Integration** (`tests/integration/`) — dual-mode via `httpx.MockTransport` in `conftest.py` (live when `PROOF_BASE_URL`+`PROOF_API_KEY_TEST` are set). Live staging is behind Cloudflare Access; header injection happens ONLY in `conftest.py`'s `_patch_client_with_cf_access` (production client stays unaware). Any client rebuild must go through `_sdk_default_headers()` to preserve the branded `proof-sdk-python/<VERSION>` UA. See `../CLAUDE.md` for the CF-Access / User-Agent / phone-identifier invariants.
+
+Invoke (mock): `pytest tests/integration/`.
+
+## Related Documentation
+- `../CLAUDE.md` - SDK suite overview (cross-SDK invariants).
+- `../../docs/api-map.yaml` - API parity map.

proof_holdings_sdk-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Proof Holdings
+
+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.

proof_holdings_sdk-1.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.5
+Name: proof-holdings-sdk
+Version: 1.1.0
+Summary: Official Python SDK for the proof.holdings verification API
+Project-URL: Homepage, https://proof.holdings
+Project-URL: Documentation, https://api.proof.holdings/api/docs/
+Project-URL: Repository, https://github.com/ProofHoldings/sdk-python
+Author: proof.holdings
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,authentication,jwt,proof-holdings,sdk,verification
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: typing-extensions>=4.0
+Provides-Extra: jwt
+Requires-Dist: pyjwt>=2.8.0; extra == 'jwt'
+Description-Content-Type: text/markdown
+
+# proof-holdings-sdk
+
+Official Python SDK for the [proof.holdings](https://proof.holdings) verification API.
+
+## Installation
+
+```bash
+pip install proof-holdings-sdk
+```
+
+For offline JWT verification:
+
+```bash
+pip install 'proof-holdings-sdk[jwt]'
+```
+
+## Quick Start
+
+```python
+import asyncio
+from proof_sdk import Proof
+
+async def main():
+    async with Proof("pk_live_...") as proof:
+        # Create a phone verification
+        v = await proof.verifications.create(
+            type="phone",
+            channel="whatsapp",
+            identifier="+1234567890",
+        )
+        print(f"Verification {v['id']} created: {v['status']}")
+
+        # Wait for user to complete verification
+        result = await proof.verifications.wait_for_completion(v["id"])
+        print(f"Result: {result['status']}")
+
+asyncio.run(main())
+```
+
+## Resources
+
+### Verifications
+
+```python
+# Create
+v = await proof.verifications.create(type="domain", channel="dns", identifier="example.com")
+
+# Retrieve
+v = await proof.verifications.retrieve("ver_abc123")
+
+# List with filters
+page = await proof.verifications.list(status="verified", type="phone", limit=10)
+
+# Trigger DNS/HTTP check
+v = await proof.verifications.verify("ver_abc123")
+
+# Submit OTP code
+v = await proof.verifications.submit("ver_abc123", code="ABC123")
+
+# Poll until complete
+v = await proof.verifications.wait_for_completion("ver_abc123", interval=2.0, timeout=300.0)
+
+# WABA (WhatsApp Business) verification
+v = await proof.verifications.create(type="waba", channel="waba_otp", identifier="+37069199199")
+# OTP is sent via WhatsApp — submit with proof.verifications.submit(v["id"], code="123456")
+
+# Telegram Bot verification
+v = await proof.verifications.create(
+    type="telegram_bot", channel="telegram_bot_token", identifier="@mybusinessbot"
+)
+# Submit bot token with proof.verifications.submit(v["id"], code="bot_token_here")
+```
+
+### Verification Requests (Multi-Asset)
+
+```python
+# Create multi-asset request
+req = await proof.verification_requests.create(
+    assets=[
+        {"type": "phone", "required": True},
+        {"type": "email", "identifier": "user@example.com"},
+    ],
+    reference_id="user_123",
+    callback_url="https://yourapp.com/webhook",
+    expires_in=86400,  # 24 hours in seconds
+)
+print(f"Send user to: {req['verification_url']}")
+
+# Poll until complete
+result = await proof.verification_requests.wait_for_completion(req["id"])
+```
+
+### Proofs
+
+```python
+# Validate online (checks revocation)
+result = await proof.proofs.validate("eyJhbGciOi...")
+
+# Revoke
+response = await proof.proofs.revoke("ver_abc123", reason="User requested")
+
+# Get revocation list
+revoked = await proof.proofs.list_revoked()
+
+# Offline verification (requires proof-holdings-sdk[jwt]) — no API call with your key. Reads two public
+# documents: the JWKS for the signature, and the issuer's status list for revocation, which is
+# checked by default.
+result = await proof.proofs.verify_offline("eyJhbGciOi...")
+if not result["valid"]:
+    # "revoked" | "suspended" | "expired" | "invalid" | "status_unavailable"
+    # | "key_revoked" | "jwks_stale" | "wrong_key_purpose" | "outside_key_window"
+    # | "token_lifetime_exceeded" | "unknown_key" — see "Signing-key rotation" below
+    print(result["reason"])
+
+# "status_unavailable" means the revocation status could NOT be read — an unreachable list, one
+# that failed its own checks, or a slot the list does not cover. It is a refusal to guess, not a
+# claim that the proof is withdrawn. A token minted without a status-list slot stays valid and
+# reports revocation_checked=False, exactly as the issuer's own validate answers for it.
+
+# Signature only, for an air-gapped check against a warm key cache:
+signature_only = await proof.proofs.verify_offline("eyJhbGciOi...", check_revocation=False)
+assert signature_only["revocation_checked"] is False  # never assume it was checked
+```
+
+### Signing-key rotation
+
+`verify_offline` fetches and caches the issuer's key set (JWKS) itself and follows its rotation
+rules. The cached set is reused for 10 minutes; a `kid` it does not know triggers one refetch, at
+most once every 30 seconds.
+
+- **`key_revoked`** — the issuer revoked the key that signed the token. The result carries
+  `pull_hint: {"issuer_origin", "handle"}`: where to fetch the re-signed token (`handle` is the
+  proof's `proof_id`, or a delegation's `sub`). The handle is read from the token itself, whose
+  signature a revoked key no longer vouches for: URL-encode it before building a request from it. A
+  revocation takes effect only after two key-set fetches at least 5 minutes apart both carry it, and
+  is then kept for a year.
+- **`jwks_stale`** — the key set could not be refreshed and the cached copy is older than
+  `max_jwks_age` (seconds; default 24 hours, at most 25 days; `Proof(key, max_jwks_age=...)`). The
+  result carries `cache_age_seconds`. Call `refresh_jwks()` once the issuer is reachable.
+- **`wrong_key_purpose`**, **`outside_key_window`**, **`token_lifetime_exceeded`** — the key belongs
+  to another token family, the token was signed outside the key's validity window, or it lives
+  longer than the key allows. **`unknown_key`** — no published key matches the token's `kid`.
+
+Revoked-key tombstones are kept in memory only — they are not persisted, so a restarted process
+learns them again from the issuer. `clear_tombstones()` forgets them on purpose. `refresh_jwks()`
+makes the next verification refetch the key set (and drops the cached status list); it does not
+forget tombstones. A tombstone naming a key last seen live is logged as a warning on the
+`proof_sdk` logger.
+
+### Sessions (Phone-First Flow)
+
+```python
+session = await proof.sessions.create(channel="telegram")
+print(f"Deep link: {session['deep_link']}")
+print(f"QR code: {session['qr_code']}")
+
+# Poll until verified
+result = await proof.sessions.wait_for_completion(session["id"])
+```
+
+### Webhook Deliveries
+
+```python
+# List deliveries
+deliveries = await proof.webhook_deliveries.list(status="failed")
+
+# Retry a failed delivery
+result = await proof.webhook_deliveries.retry("del_abc123")
+```
+
+## Error Handling
+
+```python
+from proof_sdk import Proof, NotFoundError, RateLimitError, RequestTimeoutError, ProofError
+
+async with Proof("pk_live_...") as proof:
+    try:
+        v = await proof.verifications.retrieve("nonexistent")
+    except NotFoundError as e:
+        print(f"Not found: {e.code}")
+    except RateLimitError:
+        print("Rate limited, try again later")
+    except ProofError as e:
+        print(f"API error {e.status_code}: {e.code} - {e}")
+```
+
+## Configuration
+
+```python
+proof = Proof(
+    "pk_live_...",
+    base_url="https://api.proof.holdings",  # Default
+    timeout=30.0,                            # Seconds, default 30
+    max_retries=2,                           # Default 2
+    max_jwks_age=86_400,                     # Offline verification stale bound, seconds (default 24h)
+)
+```
+
+## Credentials
+
+Sign in once with `npx @proof-holdings/mcp-server login` and construct the client with no key:
+
+```python
+proof = Proof()                              # or Proof(base_url="...")
+```
+
+When the key argument is omitted it is resolved in this order:
+
+1. `PROOF_API_KEY`, when set and non-empty.
+2. The entry for this client's base URL in `~/.proof-holdings/credentials`, the file the login
+   command writes. The file is keyed by base URL, so a key saved against staging is never sent
+   to production.
+3. Otherwise construction raises `ValueError`, naming the three roads: pass the key, set
+   `PROOF_API_KEY`, or run `npx @proof-holdings/mcp-server login`.
+
+The base URL is the `base_url` argument, else a non-empty `PROOF_BASE_URL`, else
+`https://api.proof.holdings`. An explicit key is used as given, and an explicit empty key
+(`Proof("")`) is an error — neither reads the environment or the file.
+
+## Requirements
+
+- Python >= 3.10
+- httpx >= 0.25.0
+- cryptography >= 41.0.0 (HITL message encryption)
+- PyJWT (optional, the `jwt` extra, for offline verification)

proof_holdings_sdk-1.1.0/README.md

@@ -0,0 +1,225 @@
+# proof-holdings-sdk
+
+Official Python SDK for the [proof.holdings](https://proof.holdings) verification API.
+
+## Installation
+
+```bash
+pip install proof-holdings-sdk
+```
+
+For offline JWT verification:
+
+```bash
+pip install 'proof-holdings-sdk[jwt]'
+```
+
+## Quick Start
+
+```python
+import asyncio
+from proof_sdk import Proof
+
+async def main():
+    async with Proof("pk_live_...") as proof:
+        # Create a phone verification
+        v = await proof.verifications.create(
+            type="phone",
+            channel="whatsapp",
+            identifier="+1234567890",
+        )
+        print(f"Verification {v['id']} created: {v['status']}")
+
+        # Wait for user to complete verification
+        result = await proof.verifications.wait_for_completion(v["id"])
+        print(f"Result: {result['status']}")
+
+asyncio.run(main())
+```
+
+## Resources
+
+### Verifications
+
+```python
+# Create
+v = await proof.verifications.create(type="domain", channel="dns", identifier="example.com")
+
+# Retrieve
+v = await proof.verifications.retrieve("ver_abc123")
+
+# List with filters
+page = await proof.verifications.list(status="verified", type="phone", limit=10)
+
+# Trigger DNS/HTTP check
+v = await proof.verifications.verify("ver_abc123")
+
+# Submit OTP code
+v = await proof.verifications.submit("ver_abc123", code="ABC123")
+
+# Poll until complete
+v = await proof.verifications.wait_for_completion("ver_abc123", interval=2.0, timeout=300.0)
+
+# WABA (WhatsApp Business) verification
+v = await proof.verifications.create(type="waba", channel="waba_otp", identifier="+37069199199")
+# OTP is sent via WhatsApp — submit with proof.verifications.submit(v["id"], code="123456")
+
+# Telegram Bot verification
+v = await proof.verifications.create(
+    type="telegram_bot", channel="telegram_bot_token", identifier="@mybusinessbot"
+)
+# Submit bot token with proof.verifications.submit(v["id"], code="bot_token_here")
+```
+
+### Verification Requests (Multi-Asset)
+
+```python
+# Create multi-asset request
+req = await proof.verification_requests.create(
+    assets=[
+        {"type": "phone", "required": True},
+        {"type": "email", "identifier": "user@example.com"},
+    ],
+    reference_id="user_123",
+    callback_url="https://yourapp.com/webhook",
+    expires_in=86400,  # 24 hours in seconds
+)
+print(f"Send user to: {req['verification_url']}")
+
+# Poll until complete
+result = await proof.verification_requests.wait_for_completion(req["id"])
+```
+
+### Proofs
+
+```python
+# Validate online (checks revocation)
+result = await proof.proofs.validate("eyJhbGciOi...")
+
+# Revoke
+response = await proof.proofs.revoke("ver_abc123", reason="User requested")
+
+# Get revocation list
+revoked = await proof.proofs.list_revoked()
+
+# Offline verification (requires proof-holdings-sdk[jwt]) — no API call with your key. Reads two public
+# documents: the JWKS for the signature, and the issuer's status list for revocation, which is
+# checked by default.
+result = await proof.proofs.verify_offline("eyJhbGciOi...")
+if not result["valid"]:
+    # "revoked" | "suspended" | "expired" | "invalid" | "status_unavailable"
+    # | "key_revoked" | "jwks_stale" | "wrong_key_purpose" | "outside_key_window"
+    # | "token_lifetime_exceeded" | "unknown_key" — see "Signing-key rotation" below
+    print(result["reason"])
+
+# "status_unavailable" means the revocation status could NOT be read — an unreachable list, one
+# that failed its own checks, or a slot the list does not cover. It is a refusal to guess, not a
+# claim that the proof is withdrawn. A token minted without a status-list slot stays valid and
+# reports revocation_checked=False, exactly as the issuer's own validate answers for it.
+
+# Signature only, for an air-gapped check against a warm key cache:
+signature_only = await proof.proofs.verify_offline("eyJhbGciOi...", check_revocation=False)
+assert signature_only["revocation_checked"] is False  # never assume it was checked
+```
+
+### Signing-key rotation
+
+`verify_offline` fetches and caches the issuer's key set (JWKS) itself and follows its rotation
+rules. The cached set is reused for 10 minutes; a `kid` it does not know triggers one refetch, at
+most once every 30 seconds.
+
+- **`key_revoked`** — the issuer revoked the key that signed the token. The result carries
+  `pull_hint: {"issuer_origin", "handle"}`: where to fetch the re-signed token (`handle` is the
+  proof's `proof_id`, or a delegation's `sub`). The handle is read from the token itself, whose
+  signature a revoked key no longer vouches for: URL-encode it before building a request from it. A
+  revocation takes effect only after two key-set fetches at least 5 minutes apart both carry it, and
+  is then kept for a year.
+- **`jwks_stale`** — the key set could not be refreshed and the cached copy is older than
+  `max_jwks_age` (seconds; default 24 hours, at most 25 days; `Proof(key, max_jwks_age=...)`). The
+  result carries `cache_age_seconds`. Call `refresh_jwks()` once the issuer is reachable.
+- **`wrong_key_purpose`**, **`outside_key_window`**, **`token_lifetime_exceeded`** — the key belongs
+  to another token family, the token was signed outside the key's validity window, or it lives
+  longer than the key allows. **`unknown_key`** — no published key matches the token's `kid`.
+
+Revoked-key tombstones are kept in memory only — they are not persisted, so a restarted process
+learns them again from the issuer. `clear_tombstones()` forgets them on purpose. `refresh_jwks()`
+makes the next verification refetch the key set (and drops the cached status list); it does not
+forget tombstones. A tombstone naming a key last seen live is logged as a warning on the
+`proof_sdk` logger.
+
+### Sessions (Phone-First Flow)
+
+```python
+session = await proof.sessions.create(channel="telegram")
+print(f"Deep link: {session['deep_link']}")
+print(f"QR code: {session['qr_code']}")
+
+# Poll until verified
+result = await proof.sessions.wait_for_completion(session["id"])
+```
+
+### Webhook Deliveries
+
+```python
+# List deliveries
+deliveries = await proof.webhook_deliveries.list(status="failed")
+
+# Retry a failed delivery
+result = await proof.webhook_deliveries.retry("del_abc123")
+```
+
+## Error Handling
+
+```python
+from proof_sdk import Proof, NotFoundError, RateLimitError, RequestTimeoutError, ProofError
+
+async with Proof("pk_live_...") as proof:
+    try:
+        v = await proof.verifications.retrieve("nonexistent")
+    except NotFoundError as e:
+        print(f"Not found: {e.code}")
+    except RateLimitError:
+        print("Rate limited, try again later")
+    except ProofError as e:
+        print(f"API error {e.status_code}: {e.code} - {e}")
+```
+
+## Configuration
+
+```python
+proof = Proof(
+    "pk_live_...",
+    base_url="https://api.proof.holdings",  # Default
+    timeout=30.0,                            # Seconds, default 30
+    max_retries=2,                           # Default 2
+    max_jwks_age=86_400,                     # Offline verification stale bound, seconds (default 24h)
+)
+```
+
+## Credentials
+
+Sign in once with `npx @proof-holdings/mcp-server login` and construct the client with no key:
+
+```python
+proof = Proof()                              # or Proof(base_url="...")
+```
+
+When the key argument is omitted it is resolved in this order:
+
+1. `PROOF_API_KEY`, when set and non-empty.
+2. The entry for this client's base URL in `~/.proof-holdings/credentials`, the file the login
+   command writes. The file is keyed by base URL, so a key saved against staging is never sent
+   to production.
+3. Otherwise construction raises `ValueError`, naming the three roads: pass the key, set
+   `PROOF_API_KEY`, or run `npx @proof-holdings/mcp-server login`.
+
+The base URL is the `base_url` argument, else a non-empty `PROOF_BASE_URL`, else
+`https://api.proof.holdings`. An explicit key is used as given, and an explicit empty key
+(`Proof("")`) is an error — neither reads the environment or the file.
+
+## Requirements
+
+- Python >= 3.10
+- httpx >= 0.25.0
+- cryptography >= 41.0.0 (HITL message encryption)
+- PyJWT (optional, the `jwt` extra, for offline verification)

proof_holdings_sdk-1.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "proof-holdings-sdk"
+version = "1.1.0"
+description = "Official Python SDK for the proof.holdings verification API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "proof.holdings" },
+]
+keywords = ["proof-holdings", "verification", "sdk", "authentication", "api", "jwt"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "typing-extensions>=4.0",
+    "cryptography>=41.0.0",
+]
+
+[project.optional-dependencies]
+jwt = [
+    "PyJWT>=2.8.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/proof_sdk"]
+
+[project.urls]
+Homepage = "https://proof.holdings"
+Documentation = "https://api.proof.holdings/api/docs/"
+Repository = "https://github.com/ProofHoldings/sdk-python"

proof_holdings_sdk-1.1.0/pytest.ini

@@ -0,0 +1,2 @@
+[pytest]
+asyncio_mode = auto

proof_holdings_sdk-1.1.0/release-fingerprint.json

@@ -0,0 +1,5 @@
+{
+  "package": "proof-holdings-sdk",
+  "version": "1.1.0",
+  "sha256": "c0cdff1e9c195a192dfac801d9489614bf3a27ad95fa870aece8a27e27d22698"
+}

proof_holdings_sdk-1.1.0/src/proof_sdk/__init__.py

@@ -0,0 +1,38 @@
+"""Official Python SDK for the proof.holdings verification API."""
+
+from .client import Proof
+from .credentials import LOGIN_COMMAND, ResolvedKey, resolve_api_key, resolve_base_url
+from .errors import (
+    ProofError,
+    ValidationError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    ConflictError,
+    RateLimitError,
+    ServerError,
+    NetworkError,
+    RequestTimeoutError,
+    PollingTimeoutError,
+)
+from .version import VERSION
+
+__all__ = [
+    "Proof",
+    "ProofError",
+    "ValidationError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+    "NetworkError",
+    "RequestTimeoutError",
+    "PollingTimeoutError",
+    "LOGIN_COMMAND",
+    "ResolvedKey",
+    "resolve_api_key",
+    "resolve_base_url",
+    "VERSION",
+]