orangecheck 2.2.0__tar.gz → 2.3.0__tar.gz

{orangecheck-2.2.0 → orangecheck-2.3.0}/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to the **`orangecheck`** Python package. Follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 [Semantic Versioning](https://semver.org/).
 
+## [2.3.0] — 2026-10-20
+
+For a site that signs people in with ochk.app and runs a Python backend.
+
+### Added
+
+- `verify_session(token, audience)` verifies a token from the sign-in popup
+  against `https://ochk.io/.well-known/jwks.json` (cached for an hour, kept
+  through an outage) and returns a `Session` with `did_oc`, `sub`, `jti`,
+  `exp` and any `oc_bond`. The audience is the exact origin of the page that
+  opened the popup; a token for any other origin, or with no `aud`, raises
+  `InvalidSession` with a one-word `reason`.
+- `sign_event(secret, body)` builds the `X-OC-Signature` header for
+  `/api/integrator/event`: HMAC-SHA256 keyed by the secret's text over
+  `f"{t}.{body}"`.
+- `verify_webhook(headers, body)` checks a delivery's Ed25519 signature
+  against `https://me.ochk.io/api/dev-jwks` and returns the parsed event, or
+  raises `InvalidWebhook`.
+- These are held to `me-client/test-vectors/integrator.json`, the same vectors
+  `@orangecheck/me-client` is tested against.
+
+### Changed
+
+- `cryptography` (41 or later) is now a dependency, for Ed25519.
+
+### Fixed
+
+- `build_canonical_message` and `format_identities` accept the
+  `IdentityBinding` exported as `orangecheck.IdentityBinding`. They took only
+  the canonical module's own class or a dict, so the documented example raised
+  `TypeError`.
+
 ## [2.2.0] — 2026-10-16
 
 Matches `@orangecheck/sdk` 1.13.0 and the spec's regenerated `tv24`–`tv27`.

{orangecheck-2.2.0 → orangecheck-2.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: orangecheck
-Version: 2.2.0
-Summary: Python SDK for OrangeCheck — proof of Bitcoin stake + the OC Pledge primitive (commitments) for the open web.
+Version: 2.3.0
+Summary: Python SDK for OrangeCheck — proof of Bitcoin stake, the OC Pledge primitive, and ochk.app sign-in for your backend.
 Project-URL: Homepage, https://ochk.io
 Project-URL: Documentation, https://ochk.io/docs
 Project-URL: Repository, https://github.com/orangecheck/oc-packages
@@ -22,6 +22,7 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Security
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
+Requires-Dist: cryptography>=41
 Requires-Dist: httpx>=0.25
 Provides-Extra: dev
 Requires-Dist: bip322>=0.2; extra == 'dev'
@@ -198,6 +199,34 @@ asyncio.run(main())
 
 ---
 
+## ochk.app sign-in, for your backend
+
+A site whose people sign in with ochk.app verifies the token the popup hands
+back, signs billable events and checks webhooks with three functions. They
+speak the same wire formats as `@orangecheck/me-client`.
+
+```python
+import json, httpx
+from orangecheck import verify_session, sign_event, verify_webhook, InvalidSession
+
+# The origin of the page that opened the popup, exactly.
+session = verify_session(token, audience="https://your-site.example")
+session.did_oc  # who signed in
+
+body = json.dumps({"project_key": PROJECT_KEY, "subtype": "account_created",
+                   "user_address": session.did_oc})
+httpx.post("https://me.ochk.io/api/integrator/event", content=body, headers={
+    "Content-Type": "application/json",
+    "X-OC-Signature": sign_event(SIGNING_SECRET, body),
+})
+
+event = verify_webhook(request.headers, raw_body)  # raises InvalidWebhook
+```
+
+The full guide is at [ochk.io/docs/sdk/python](https://ochk.io/docs/sdk/python).
+
+---
+
 ## Configuration
 
 ```python
@@ -261,4 +290,4 @@ Exits `0` on pass, `2` on fail. Prefer the TypeScript `oc` CLI for richer output
 
 ## License
 
-MIT. The OrangeCheck protocol is CC-BY-4.0.
+MIT. The OrangeCheck protocol specifications are MIT too.

{orangecheck-2.2.0 → orangecheck-2.3.0}/README.md

@@ -162,6 +162,34 @@ asyncio.run(main())
 
 ---
 
+## ochk.app sign-in, for your backend
+
+A site whose people sign in with ochk.app verifies the token the popup hands
+back, signs billable events and checks webhooks with three functions. They
+speak the same wire formats as `@orangecheck/me-client`.
+
+```python
+import json, httpx
+from orangecheck import verify_session, sign_event, verify_webhook, InvalidSession
+
+# The origin of the page that opened the popup, exactly.
+session = verify_session(token, audience="https://your-site.example")
+session.did_oc  # who signed in
+
+body = json.dumps({"project_key": PROJECT_KEY, "subtype": "account_created",
+                   "user_address": session.did_oc})
+httpx.post("https://me.ochk.io/api/integrator/event", content=body, headers={
+    "Content-Type": "application/json",
+    "X-OC-Signature": sign_event(SIGNING_SECRET, body),
+})
+
+event = verify_webhook(request.headers, raw_body)  # raises InvalidWebhook
+```
+
+The full guide is at [ochk.io/docs/sdk/python](https://ochk.io/docs/sdk/python).
+
+---
+
 ## Configuration
 
 ```python
@@ -225,4 +253,4 @@ Exits `0` on pass, `2` on fail. Prefer the TypeScript `oc` CLI for richer output
 
 ## License
 
-MIT. The OrangeCheck protocol is CC-BY-4.0.
+MIT. The OrangeCheck protocol specifications are MIT too.

{orangecheck-2.2.0 → orangecheck-2.3.0}/orangecheck/__init__.py

@@ -23,6 +23,11 @@ a custom API base URL, timeouts, or a shared httpx session:
     from orangecheck import AsyncClient
     async with AsyncClient() as oc:
         result = await oc.check(addr="bc1q...", min_sats=100_000)
+
+A site that signs people in with ochk.app verifies the sign-in token, signs
+billable events and checks webhooks with three more:
+
+    from orangecheck import verify_session, sign_event, verify_webhook
 """
 
 from .canonical import (
@@ -55,6 +60,14 @@ from .bond import (
 )
 from .client import AsyncClient, Client
 from .errors import OrangeCheckError, RateLimitError, VerificationError
+from .integrator import (
+    InvalidSession,
+    InvalidWebhook,
+    Session,
+    sign_event,
+    verify_session,
+    verify_webhook,
+)
 from .top_level import challenge_issue, challenge_verify, check, discover, verify
 from .types import (
     AttestationSummary,
@@ -99,6 +112,13 @@ __all__ = [
     "BOND_SATS_FLOORS",
     "BOND_DAYS_FLOORS",
     "BOND_MAX_WINDOW_SECONDS",
+    # ochk.app sign-in, billable events and webhooks, for an integrator's backend
+    "verify_session",
+    "sign_event",
+    "verify_webhook",
+    "Session",
+    "InvalidSession",
+    "InvalidWebhook",
     # Types
     "CheckResult",
     "VerifyOutcome",
@@ -113,7 +133,7 @@ __all__ = [
     "VerificationError",
 ]
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 # OC Pledge submodule — sibling primitive for forward-looking commitments
 # bound to a Bitcoin address. Imported here so consumers can write:

{orangecheck-2.2.0 → orangecheck-2.3.0}/orangecheck/canonical.py

@@ -25,7 +25,9 @@ import re
 import secrets
 from dataclasses import dataclass
 from datetime import datetime, timezone
-from typing import Mapping, Sequence
+from typing import Mapping, Sequence, Union
+
+from . import types as _types
 
 # ─── Identity safety rules ─────────────────────────────────────────────────
 
@@ -48,6 +50,11 @@ class IdentityBinding:
     identifier: str
 
 
+#: Either binding class (``orangecheck.IdentityBinding`` is the one in types),
+#: or a plain dict with ``protocol`` / ``identifier`` keys.
+IdentityLike = Union[IdentityBinding, _types.IdentityBinding, Mapping[str, str]]
+
+
 def _assert_safe_identity(id: IdentityBinding) -> None:
     if not _IDENTITY_PROTOCOL_RE.fullmatch(id.protocol):
         raise ValueError(
@@ -60,24 +67,26 @@ def _assert_safe_identity(id: IdentityBinding) -> None:
         )
 
 
-def format_identities(identities: Sequence[IdentityBinding | Mapping[str, str]]) -> str:
+def format_identities(identities: Sequence[IdentityLike]) -> str:
     """
     Format identities as comma-separated ``protocol:identifier`` pairs, sorted
     lexicographically. Rejects unsafe characters at the boundary (see
     ``_assert_safe_identity``).
 
-    Accepts either ``IdentityBinding`` instances or plain dicts with
-    ``protocol`` / ``identifier`` keys (for JSON interop).
+    Accepts ``IdentityBinding`` instances, including the one exported as
+    ``orangecheck.IdentityBinding``, or plain dicts with ``protocol`` /
+    ``identifier`` keys (for JSON interop).
     """
     if not identities:
         return ""
     normalized: list[IdentityBinding] = []
     for item in identities:
-        b = (
-            item
-            if isinstance(item, IdentityBinding)
-            else IdentityBinding(protocol=item["protocol"], identifier=item["identifier"])
-        )
+        if isinstance(item, IdentityBinding):
+            b = item
+        elif isinstance(item, _types.IdentityBinding):
+            b = IdentityBinding(protocol=item.protocol, identifier=item.identifier)
+        else:
+            b = IdentityBinding(protocol=item["protocol"], identifier=item["identifier"])
         _assert_safe_identity(b)
         normalized.append(b)
     return ",".join(sorted(f"{b.protocol}:{b.identifier}" for b in normalized))
@@ -129,7 +138,7 @@ def _now_rfc3339_utc() -> str:
 def build_canonical_message(
     *,
     address: str,
-    identities: Sequence[IdentityBinding | Mapping[str, str]] = (),
+    identities: Sequence[IdentityLike] = (),
     extensions: Mapping[str, str | int | None] | None = None,
     nonce: str | None = None,
     issued_at: str | None = None,

orangecheck-2.3.0/orangecheck/integrator.py

@@ -0,0 +1,327 @@
+"""
+Helpers for a site's own backend when it signs people in with ochk.app.
+
+Three jobs, the same wire formats as ``@orangecheck/me-client``:
+
+    from orangecheck import verify_session, sign_event, verify_webhook
+
+    session = verify_session(token, audience="https://your-site.example")
+    header = sign_event(signing_secret, body)          # X-OC-Signature
+    event = verify_webhook(request.headers, raw_body)
+
+Both SDKs are held to one set of vectors
+(``me-client/test-vectors/integrator.json``), so they accept and refuse the
+same tokens, signatures and deliveries.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+import threading
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Optional, Union
+
+import httpx
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from .errors import OrangeCheckError
+
+#: The auth host. Sign-in tokens name it as ``iss``; its key set signs them.
+SESSION_ISSUER = "https://ochk.io"
+SESSION_JWKS_URL = "https://ochk.io/.well-known/jwks.json"
+#: me.ochk.io signs webhook deliveries with its own key (the path is historical).
+WEBHOOK_JWKS_URL = "https://me.ochk.io/api/dev-jwks"
+
+_JWKS_TTL_SECONDS = 3600
+_FORCED_REFRESH_MIN_SECONDS = 60
+
+
+class InvalidSession(OrangeCheckError):
+    """The sign-in token did not verify. ``reason`` says why, in one word."""
+
+    def __init__(self, reason: str, message: str | None = None):
+        super().__init__(message or f"session token refused: {reason}")
+        self.reason = reason
+
+
+class InvalidWebhook(OrangeCheckError):
+    """The webhook delivery did not verify. ``reason`` says why, in one word."""
+
+    def __init__(self, reason: str, message: str | None = None):
+        super().__init__(message or f"webhook refused: {reason}")
+        self.reason = reason
+
+
+@dataclass(frozen=True)
+class Session:
+    """A verified sign-in. ``did_oc`` is the person; ``sub`` is their account id."""
+
+    sub: str
+    did_oc: str
+    jti: str
+    aud: Union[str, list[str]]
+    iat: Optional[int]
+    exp: int
+    #: Coin backing, when the person backed their account (see require-bond).
+    oc_bond: Optional[dict[str, Any]] = None
+    claims: dict[str, Any] = field(default_factory=dict)
+
+
+# ─── key sets ────────────────────────────────────────────────────────────
+
+
+class _KeySet:
+    """A fetched JWKS, cached for an hour and kept through a failed refresh."""
+
+    def __init__(self, url: str):
+        self.url = url
+        self._keys: dict[str, Ed25519PublicKey] = {}
+        self._fetched_at = 0.0
+        self._forced_at = 0.0
+        self._lock = threading.Lock()
+
+    def _fetch(self) -> None:
+        try:
+            r = httpx.get(self.url, headers={"Accept": "application/json"}, timeout=10.0)
+            r.raise_for_status()
+            self._keys = _import_jwks(r.json())
+            self._fetched_at = time.time()
+        except (httpx.HTTPError, ValueError):
+            # Stale on error: a key set seen before keeps working through an outage.
+            if not self._keys:
+                raise
+
+    def get(self, kid: str) -> Optional[Ed25519PublicKey]:
+        with self._lock:
+            if not self._keys or time.time() - self._fetched_at >= _JWKS_TTL_SECONDS:
+                self._fetch()
+            key = self._keys.get(kid)
+            # A key that rotated in since the last fetch: refetch, at most once a minute.
+            if key is None and time.time() - self._forced_at >= _FORCED_REFRESH_MIN_SECONDS:
+                self._forced_at = time.time()
+                self._fetch()
+                key = self._keys.get(kid)
+            return key
+
+
+_session_keys = _KeySet(SESSION_JWKS_URL)
+_webhook_keys = _KeySet(WEBHOOK_JWKS_URL)
+
+
+def _b64url(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def _import_jwks(doc: Any) -> dict[str, Ed25519PublicKey]:
+    if not isinstance(doc, dict) or not isinstance(doc.get("keys"), list):
+        raise ValueError("JWKS did not return {keys: [...]}")
+    keys: dict[str, Ed25519PublicKey] = {}
+    for k in doc["keys"]:
+        if not isinstance(k, dict) or not isinstance(k.get("kid"), str):
+            continue
+        if k.get("kty") != "OKP" or k.get("crv") != "Ed25519" or not isinstance(k.get("x"), str):
+            continue
+        try:
+            keys[k["kid"]] = Ed25519PublicKey.from_public_bytes(_b64url(k["x"]))
+        except (ValueError, binascii.Error):
+            continue
+    return keys
+
+
+# ─── sign-in tokens ──────────────────────────────────────────────────────
+
+
+def verify_session(
+    token: str,
+    audience: Union[str, list[str]],
+    *,
+    jwks: Optional[Mapping[str, Any]] = None,
+    issuer: str = SESSION_ISSUER,
+    leeway: int = 0,
+) -> Session:
+    """
+    Verify a token from the ochk.app sign-in popup and return who signed in.
+
+    ``audience`` is the origin of the page that opened the popup, exactly
+    (``https://your-site.example``, or ``http://localhost:5173`` while you
+    develop). A token issued to any other origin, or a family token with no
+    ``aud`` at all, is refused. The key set is fetched from
+    ``https://ochk.io/.well-known/jwks.json`` and cached for an hour; pass
+    ``jwks`` to verify offline.
+
+    Raises :class:`InvalidSession` on any failure. The token proves who signed
+    in until it expires (up to 30 days); it does not prove the person has not
+    signed out since. Keep your own session, and see the docs on ending one.
+    """
+    parts = token.split(".") if isinstance(token, str) else []
+    if len(parts) != 3:
+        raise InvalidSession("malformed")
+    try:
+        header = json.loads(_b64url(parts[0]))
+        payload = json.loads(_b64url(parts[1]))
+        signature = _b64url(parts[2])
+    except (ValueError, binascii.Error) as err:
+        raise InvalidSession("malformed") from err
+    if not isinstance(header, dict) or not isinstance(payload, dict):
+        raise InvalidSession("malformed")
+    if header.get("alg") != "EdDSA":
+        raise InvalidSession("algorithm")
+    if "crit" in header:
+        raise InvalidSession("malformed")
+    kid = header.get("kid")
+    if not isinstance(kid, str) or not kid:
+        raise InvalidSession("malformed")
+
+    if jwks is not None:
+        try:
+            key = _import_jwks(dict(jwks)).get(kid)
+        except ValueError as err:
+            raise InvalidSession("unknown_key") from err
+    else:
+        try:
+            key = _session_keys.get(kid)
+        except (httpx.HTTPError, ValueError) as err:
+            raise InvalidSession("key_set_unavailable") from err
+    if key is None:
+        raise InvalidSession("unknown_key")
+    try:
+        key.verify(signature, f"{parts[0]}.{parts[1]}".encode("ascii"))
+    except InvalidSignature as err:
+        raise InvalidSession("signature") from err
+
+    if payload.get("iss") != issuer:
+        raise InvalidSession("issuer")
+    now = time.time()
+    exp = payload.get("exp")
+    if not isinstance(exp, (int, float)) or isinstance(exp, bool):
+        raise InvalidSession("claims")
+    if exp <= now - leeway:
+        raise InvalidSession("expired")
+    nbf = payload.get("nbf")
+    if nbf is not None and (not isinstance(nbf, (int, float)) or nbf > now + leeway):
+        raise InvalidSession("not_yet_valid")
+    iat = payload.get("iat")
+    if iat is not None and not isinstance(iat, (int, float)):
+        raise InvalidSession("claims")
+    for claim in ("sub", "did_oc", "jti"):
+        if not isinstance(payload.get(claim), str) or not payload[claim]:
+            raise InvalidSession("claims")
+
+    aud = payload.get("aud")
+    have = aud if isinstance(aud, list) else ([] if aud is None else [aud])
+    want = [audience] if isinstance(audience, str) else list(audience)
+    if not any(isinstance(a, str) and a in want for a in have):
+        raise InvalidSession("audience")
+
+    bond = payload.get("oc_bond")
+    return Session(
+        sub=payload["sub"],
+        did_oc=payload["did_oc"],
+        jti=payload["jti"],
+        aud=list(aud) if isinstance(aud, list) else str(aud),
+        iat=int(iat) if iat is not None else None,
+        exp=int(exp),
+        oc_bond=bond if isinstance(bond, dict) else None,
+        claims=payload,
+    )
+
+
+# ─── billable events ─────────────────────────────────────────────────────
+
+
+def sign_event(
+    secret: str, body: Union[str, bytes], *, timestamp: Optional[int] = None
+) -> str:
+    """
+    The ``X-OC-Signature`` header for a request to ``/api/integrator/event``.
+
+    ``body`` must be the exact bytes you send; serialise once and send that
+    string. The key is the signing secret's text as UTF-8 (it is not
+    hex-decoded), and the MAC covers ``f"{t}.{body}"``. me.ochk.io refuses a
+    timestamp more than 300 seconds from its clock.
+
+        body = json.dumps({"project_key": key, "subtype": "account_created",
+                           "user_address": session.did_oc})
+        httpx.post(url, content=body, headers={
+            "Content-Type": "application/json",
+            "X-OC-Signature": sign_event(secret, body),
+        })
+    """
+    t = int(time.time()) if timestamp is None else int(timestamp)
+    raw = body.encode("utf-8") if isinstance(body, str) else bytes(body)
+    mac = hmac.new(secret.encode("utf-8"), f"{t}.".encode("ascii") + raw, hashlib.sha256)
+    return f"t={t},v1={mac.hexdigest()}"
+
+
+# ─── webhooks ────────────────────────────────────────────────────────────
+
+
+def _header(headers: Mapping[str, Any], name: str) -> Optional[str]:
+    want = name.lower()
+    for k, v in headers.items():
+        if isinstance(k, str) and k.lower() == want:
+            return v if isinstance(v, str) else None
+    return None
+
+
+def verify_webhook(
+    headers: Mapping[str, Any],
+    body: Union[str, bytes],
+    *,
+    jwks: Optional[Mapping[str, Any]] = None,
+) -> dict[str, Any]:
+    """
+    Verify a webhook from me.ochk.io and return its parsed body.
+
+    Pass the request headers and the raw body, before any JSON parsing. The
+    signature is Ed25519 over those bytes: ``OC-Signature`` (hex) under the key
+    named by ``OC-Key-Id``, from ``https://me.ochk.io/api/dev-jwks`` (cached for
+    an hour; pass ``jwks`` to verify offline). The signature carries no
+    timestamp, and a delivery may arrive more than once, so deduplicate on
+    ``OC-Envelope-Id``.
+
+    Raises :class:`InvalidWebhook` on any failure.
+    """
+    sig_hex = _header(headers, "OC-Signature")
+    kid = _header(headers, "OC-Key-Id")
+    if not sig_hex or not kid:
+        raise InvalidWebhook("missing")
+    try:
+        signature = bytes.fromhex(sig_hex.strip())
+    except ValueError as err:
+        raise InvalidWebhook("malformed") from err
+    if len(signature) != 64:
+        raise InvalidWebhook("malformed")
+
+    if jwks is not None:
+        try:
+            key = _import_jwks(dict(jwks)).get(kid)
+        except ValueError as err:
+            raise InvalidWebhook("unknown_key") from err
+    else:
+        try:
+            key = _webhook_keys.get(kid)
+        except (httpx.HTTPError, ValueError) as err:
+            raise InvalidWebhook("key_set_unavailable") from err
+    if key is None:
+        raise InvalidWebhook("unknown_key")
+
+    raw = body.encode("utf-8") if isinstance(body, str) else bytes(body)
+    try:
+        key.verify(signature, raw)
+    except InvalidSignature as err:
+        raise InvalidWebhook("signature") from err
+    try:
+        parsed = json.loads(raw)
+    except ValueError as err:
+        raise InvalidWebhook("malformed") from err
+    if not isinstance(parsed, dict):
+        raise InvalidWebhook("malformed")
+    return parsed

{orangecheck-2.2.0 → orangecheck-2.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "orangecheck"
-version = "2.2.0"
-description = "Python SDK for OrangeCheck — proof of Bitcoin stake + the OC Pledge primitive (commitments) for the open web."
+version = "2.3.0"
+description = "Python SDK for OrangeCheck — proof of Bitcoin stake, the OC Pledge primitive, and ochk.app sign-in for your backend."
 readme = "README.md"
 license = { text = "MIT" }
 authors = [{ name = "OrangeCheck" }]
@@ -34,6 +34,8 @@ classifiers = [
 ]
 dependencies = [
     "httpx>=0.25",
+    # Ed25519 for ochk.app sign-in tokens and webhook signatures (integrator.py).
+    "cryptography>=41",
 ]
 
 [project.urls]

{orangecheck-2.2.0 → orangecheck-2.3.0}/tests/test_conformance.py

@@ -213,3 +213,19 @@ def test_vector_set_complete() -> None:
         "bond_floors",
     }
     assert len(VECTORS) >= 28
+
+
+def test_build_accepts_the_exported_identity_binding() -> None:
+    # orangecheck.IdentityBinding (types) and the canonical module's class are
+    # separate; the docs build messages with the exported one.
+    from orangecheck import IdentityBinding
+
+    kw = dict(address="bc1qalice", nonce="a3f5b8c2d1e4f6a7b8c9d0e1f2a3b4c5",
+              issued_at="2026-04-24T06:47:29.977Z")
+    exported = build_canonical_message(
+        identities=[IdentityBinding(protocol="github", identifier="alice")], **kw
+    )
+    as_dict = build_canonical_message(
+        identities=[{"protocol": "github", "identifier": "alice"}], **kw
+    )
+    assert exported == as_dict

orangecheck-2.3.0/tests/test_integrator_vectors.py

@@ -0,0 +1,149 @@
+"""
+ochk.app integrator wire formats, held to me-client's vectors.
+
+``me-client/test-vectors/integrator.json`` is read here and by me-client's
+``src/__tests__/integrator-vectors.test.ts``. Both SDKs must accept every
+valid vector and refuse every invalid one, so a Python backend and a Node
+backend can't drift apart. Regenerate with
+``node me-client/scripts/gen-integrator-vectors.mjs``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import httpx
+import pytest
+import respx
+
+import orangecheck.integrator as integrator
+from orangecheck import (
+    InvalidSession,
+    InvalidWebhook,
+    sign_event,
+    verify_session,
+    verify_webhook,
+)
+
+VECTORS_PATH = Path(__file__).resolve().parents[2] / "me-client" / "test-vectors" / "integrator.json"
+V: dict[str, Any] = json.loads(VECTORS_PATH.read_text())
+
+
+@pytest.fixture(autouse=True)
+def fixed_clock(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(integrator.time, "time", lambda: float(V["now"]))
+
+
+@pytest.fixture
+def fresh_key_sets(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(integrator, "_session_keys", integrator._KeySet(integrator.SESSION_JWKS_URL))
+    monkeypatch.setattr(integrator, "_webhook_keys", integrator._KeySet(integrator.WEBHOOK_JWKS_URL))
+
+
+# ─── sign-in tokens ──────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize("v", V["session"]["valid"], ids=lambda v: v["name"])
+def test_session_accepts(v: dict[str, Any]) -> None:
+    s = verify_session(v["token"], v["audience"], jwks=V["session"]["jwks"])
+    for k, want in v["claims"].items():
+        assert s.claims[k] == want
+    assert s.did_oc == v["claims"]["did_oc"]
+    assert s.sub == v["claims"]["sub"]
+
+
+@pytest.mark.parametrize("v", V["session"]["invalid"], ids=lambda v: v["name"])
+def test_session_refuses(v: dict[str, Any]) -> None:
+    with pytest.raises(InvalidSession) as err:
+        verify_session(v["token"], v["audience"], jwks=V["session"]["jwks"])
+    assert err.value.reason == v["reason"]
+
+
+@respx.mock
+def test_session_fetches_the_ochk_io_key_set_once(fresh_key_sets: None) -> None:
+    route = respx.get("https://ochk.io/.well-known/jwks.json").mock(
+        return_value=httpx.Response(200, json=V["session"]["jwks"])
+    )
+    v = V["session"]["valid"][0]
+    verify_session(v["token"], v["audience"])
+    verify_session(v["token"], v["audience"])
+    assert route.call_count == 1
+
+
+@respx.mock
+def test_session_keeps_a_key_set_through_an_outage(fresh_key_sets: None) -> None:
+    route = respx.get("https://ochk.io/.well-known/jwks.json").mock(
+        side_effect=[httpx.Response(200, json=V["session"]["jwks"]), httpx.Response(503)]
+    )
+    v = V["session"]["valid"][0]
+    verify_session(v["token"], v["audience"])
+    # The hour is up, the refetch fails, and the keys already held still verify.
+    integrator._session_keys._fetched_at = 0.0
+    assert verify_session(v["token"], v["audience"]).did_oc == v["claims"]["did_oc"]
+    assert route.call_count == 2
+
+
+@respx.mock
+def test_session_without_any_key_set_is_refused(fresh_key_sets: None) -> None:
+    respx.get("https://ochk.io/.well-known/jwks.json").mock(return_value=httpx.Response(503))
+    v = V["session"]["valid"][0]
+    with pytest.raises(InvalidSession) as err:
+        verify_session(v["token"], v["audience"])
+    assert err.value.reason == "key_set_unavailable"
+
+
+def test_session_leeway_admits_a_token_just_expired() -> None:
+    expired = next(v for v in V["session"]["invalid"] if v["name"] == "expired")
+    s = verify_session(expired["token"], expired["audience"], jwks=V["session"]["jwks"], leeway=5)
+    assert s.did_oc
+
+
+# ─── event signatures ────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize("v", V["event"], ids=lambda v: v["name"])
+def test_sign_event_matches_the_node_sdk(v: dict[str, Any]) -> None:
+    assert sign_event(v["secret"], v["body"], timestamp=v["timestamp"]) == v["header"]
+    assert sign_event(v["secret"], v["body"].encode("utf-8"), timestamp=v["timestamp"]) == v["header"]
+
+
+@pytest.mark.parametrize("v", V["event"], ids=lambda v: v["name"])
+def test_event_body_is_what_json_dumps_gives_with_compact_separators(v: dict[str, Any]) -> None:
+    # The docs build the body with json.dumps(..., separators=(",", ":"),
+    # ensure_ascii=False); any serialisation works if you sign what you send.
+    assert json.dumps(v["fields"], separators=(",", ":"), ensure_ascii=False) == v["body"]
+
+
+def test_sign_event_uses_the_clock_by_default() -> None:
+    v = V["event"][0]
+    assert sign_event(v["secret"], v["body"]).startswith(f"t={V['now']},v1=")
+
+
+# ─── webhooks ────────────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize("v", V["webhook"]["valid"], ids=lambda v: v["name"])
+def test_webhook_accepts(v: dict[str, Any]) -> None:
+    event = verify_webhook(v["headers"], v["body"], jwks=V["webhook"]["jwks"])
+    assert event == json.loads(v["body"])
+    lower = {k.lower(): val for k, val in v["headers"].items()}
+    assert verify_webhook(lower, v["body"].encode("utf-8"), jwks=V["webhook"]["jwks"]) == event
+
+
+@pytest.mark.parametrize("v", V["webhook"]["invalid"], ids=lambda v: v["name"])
+def test_webhook_refuses(v: dict[str, Any]) -> None:
+    with pytest.raises(InvalidWebhook) as err:
+        verify_webhook(v["headers"], v["body"], jwks=V["webhook"]["jwks"])
+    assert err.value.reason == v["reason"]
+
+
+@respx.mock
+def test_webhook_fetches_me_ochk_io_dev_jwks(fresh_key_sets: None) -> None:
+    route = respx.get("https://me.ochk.io/api/dev-jwks").mock(
+        return_value=httpx.Response(200, json=V["webhook"]["jwks"])
+    )
+    v = V["webhook"]["valid"][0]
+    assert verify_webhook(v["headers"], v["body"])["id"] == "oc-me-tv-1"
+    assert route.call_count == 1