chitmark 0.1.1__py3-none-any.whl

chitmark/__init__.py

@@ -0,0 +1,45 @@
+"""Official Python SDK for Chitmark by Open Agent Ledger.
+
+Trust decisions on agent-mediated actions (verify, feedback, challenge),
+tuned by business outcomes.
+"""
+
+from chitmark.client import SDK_VERSION, Chitmark
+from chitmark.errors import ChitmarkApiError, ChitmarkError
+from chitmark.pii import hash_email_sha256, truncate_ip
+from chitmark.types import (
+    ActorType,
+    ChallengeMethod,
+    ChallengeResponse,
+    Decision,
+    FeedbackResponse,
+    Outcome,
+    Principal,
+    Subject,
+    Verdict,
+    VerdictTokenClaims,
+)
+from chitmark.verify_token import VerdictTokenError, verify_verdict_token
+
+__all__ = [
+    "SDK_VERSION",
+    "ActorType",
+    "ChallengeMethod",
+    "ChallengeResponse",
+    "Chitmark",
+    "ChitmarkApiError",
+    "ChitmarkError",
+    "Decision",
+    "FeedbackResponse",
+    "Outcome",
+    "Principal",
+    "Subject",
+    "Verdict",
+    "VerdictTokenClaims",
+    "VerdictTokenError",
+    "hash_email_sha256",
+    "truncate_ip",
+    "verify_verdict_token",
+]
+
+__version__ = SDK_VERSION

chitmark/client.py

@@ -0,0 +1,346 @@
+"""Official Python client for Chitmark by Open Agent Ledger.
+
+Trust decisions on agent-mediated actions, tuned by business outcomes.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from typing import Any, cast
+
+import httpx
+
+from chitmark.errors import ChitmarkApiError, ChitmarkError
+from chitmark.pii import hash_email_sha256, minimize_form_data, truncate_ip
+from chitmark.types import (
+    ChallengeCompletionResponse,
+    ChallengeMethod,
+    ChallengeProof,
+    ChallengeResponse,
+    ChitmarkEnv,
+    Decision,
+    FeedbackResponse,
+    OnDegraded,
+    Outcome,
+    PiiMode,
+    Subject,
+    Verdict,
+)
+
+__all__ = ["Chitmark", "DEFAULT_BASE_URLS", "SDK_VERSION"]
+
+SDK_VERSION = "0.1.0"
+
+DEFAULT_BASE_URLS: dict[ChitmarkEnv, str] = {
+    "production": "https://api.chitmark.com",
+    "staging": "https://api.staging.chitmark.com",
+    "development": "http://127.0.0.1:8787",
+}
+
+DEFAULT_TIMEOUT_MS = 800
+
+
+def _degraded_challenge_verdict(reason: str, session: str | None = None) -> Verdict:
+    """Golden rule: fail to challenge, never to allow."""
+    return {
+        "decision": "challenge",
+        "actorType": "unknown",
+        "confidence": 0.0,
+        "reasons": [reason],
+        "principal": {"resolved": False, "identityBasis": ["degraded"]},
+        "verdictToken": "",
+        "eventId": f"evt_degraded_{session or 'unknown'}",
+        "degraded": True,
+        "enforcementMode": "enforce",
+    }
+
+
+def _enforce_degraded_never_allow(verdict: Verdict) -> Verdict:
+    if verdict.get("degraded") and verdict.get("decision") == "allow":
+        reasons = list(verdict.get("reasons") or [])
+        reasons.append("Client enforced: degraded decision must not be allow")
+        return {**verdict, "decision": "challenge", "reasons": reasons}
+    return verdict
+
+
+def _is_well_formed_verdict(value: Any) -> bool:
+    """Minimal shape guard for a 200 verify response.
+
+    A malformed verdict must never be treated as allow — the gating fields
+    are what gate correctness (parity with the TypeScript SDK).
+    """
+    if not isinstance(value, dict):
+        return False
+    return (
+        value.get("decision") in {"allow", "challenge", "deny"}
+        and isinstance(value.get("eventId"), str)
+        and bool(value["eventId"])
+        and isinstance(value.get("degraded"), bool)
+    )
+
+
+def _prepare_subject(subject: Subject | Mapping[str, Any], pii_mode: PiiMode) -> Subject:
+    data = dict(subject)
+    if pii_mode == "raw":
+        return cast(Subject, data)
+
+    if pii_mode == "none":
+        headers = data.get("headers")
+        kept: Subject = {}
+        if data.get("userAgent"):
+            kept["userAgent"] = str(data["userAgent"])
+        if isinstance(headers, dict):
+            wb: dict[str, str] = {}
+            keys = {"signature-agent", "signature-input", "signature"}
+            for k, v in headers.items():
+                lk = str(k).lower()
+                if lk in keys and isinstance(v, str):
+                    wb[lk] = v
+            if wb:
+                kept["headers"] = wb
+        return kept
+
+    prepared: Subject = {}
+    if data.get("userAgent") is not None:
+        prepared["userAgent"] = str(data["userAgent"])
+    if isinstance(data.get("headers"), dict):
+        prepared["headers"] = {str(k): str(v) for k, v in data["headers"].items()}
+
+    if data.get("emailSha256"):
+        prepared["emailSha256"] = str(data["emailSha256"])
+    elif data.get("email"):
+        prepared["emailSha256"] = hash_email_sha256(str(data["email"]))
+
+    if data.get("ipTrunc"):
+        prepared["ipTrunc"] = str(data["ipTrunc"])
+    elif data.get("ip"):
+        prepared["ipTrunc"] = truncate_ip(str(data["ip"]))
+
+    form_hashed = data.get("formDataHashed")
+    if form_hashed is None and isinstance(data.get("formData"), dict):
+        form_hashed = minimize_form_data(data["formData"])
+    if form_hashed:
+        prepared["formDataHashed"] = dict(form_hashed)
+
+    return prepared
+
+
+class Chitmark:
+    """
+    Chitmark client — three verbs: verify, feedback, challenge.
+
+    Example::
+
+        from chitmark import Chitmark
+
+        client = Chitmark(api_key="ck_live_...")
+        verdict = client.verify(
+            action="signup",
+            subject={"email": "buyer@acme.com", "ip": "203.0.113.7"},
+        )
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        env: ChitmarkEnv = "production",
+        timeout_ms: int = DEFAULT_TIMEOUT_MS,
+        pii_mode: PiiMode = "hashed",
+        on_degraded: OnDegraded = "challenge",
+        client_name: str | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key:
+            raise ChitmarkError("Chitmark api_key is required")
+        if on_degraded != "challenge":
+            raise ChitmarkError(
+                'on_degraded must be "challenge" — fail to challenge, never to allow'
+            )
+
+        self._api_key = api_key
+        self._base_url = (
+            base_url or os.environ.get("CHITMARK_BASE_URL") or DEFAULT_BASE_URLS[env]
+        ).rstrip("/")
+        self._timeout = timeout_ms / 1000.0
+        self._pii_mode = pii_mode
+        self._on_degraded: OnDegraded = "challenge"
+        self._client_name = client_name or f"chitmark-python/{SDK_VERSION}"
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(
+            base_url=self._base_url,
+            timeout=self._timeout,
+            headers={
+                "Authorization": f"Bearer {self._api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": self._client_name,
+                "X-Chitmark-Client": self._client_name,
+            },
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client if owned by this instance."""
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> Chitmark:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def verify(
+        self,
+        *,
+        action: str,
+        subject: Subject | Mapping[str, Any],
+        session: str | None = None,
+        surface: str | None = None,
+        context: Mapping[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Verdict:
+        """Score + route an inbound action. Degrades to challenge on timeout/transport."""
+        body: dict[str, Any] = {
+            "action": action,
+            "subject": _prepare_subject(subject, self._pii_mode),
+        }
+        if session is not None:
+            body["session"] = session
+        if surface is not None:
+            body["surface"] = surface
+        if context is not None:
+            body["context"] = dict(context)
+        if idempotency_key is not None:
+            body["idempotencyKey"] = idempotency_key
+
+        try:
+            verdict = self._request(
+                "POST",
+                "/v1/verify",
+                body=body,
+                idempotency_key=idempotency_key,
+            )
+            if not _is_well_formed_verdict(verdict):
+                return _degraded_challenge_verdict(
+                    "Degraded: verify returned a malformed verdict shape",
+                    session,
+                )
+            return _enforce_degraded_never_allow(cast(Verdict, verdict))
+        except ChitmarkApiError:
+            raise
+        except Exception as exc:  # noqa: BLE001 — map transport to degraded
+            return _degraded_challenge_verdict(f"Degraded: {exc}", session)
+
+    def feedback(
+        self,
+        *,
+        event_id: str,
+        outcome: Outcome,
+        value: float | None = None,
+        unit: str = "usd",
+        observed_at: str | None = None,
+    ) -> FeedbackResponse:
+        """Report a downstream outcome joined on eventId."""
+        body: dict[str, Any] = {"eventId": event_id, "outcome": outcome}
+        if value is not None:
+            body["value"] = value
+        if unit is not None:
+            body["unit"] = unit
+        if observed_at is not None:
+            body["observedAt"] = observed_at
+        return cast(
+            FeedbackResponse,
+            self._request("POST", "/v1/feedback", body=body),
+        )
+
+    def challenge(
+        self,
+        *,
+        event_id: str,
+        session: str | None = None,
+        prefer: list[ChallengeMethod] | None = None,
+    ) -> ChallengeResponse:
+        """Issue an asymmetric-cost challenge."""
+        body: dict[str, Any] = {"eventId": event_id}
+        if session is not None:
+            body["session"] = session
+        if prefer is not None:
+            body["prefer"] = prefer
+        return cast(
+            ChallengeResponse,
+            self._request("POST", "/v1/challenge", body=body),
+        )
+
+    def complete_challenge(
+        self,
+        *,
+        event_id: str,
+        challenge_id: str,
+        session: str | None = None,
+        proof: ChallengeProof,
+    ) -> ChallengeCompletionResponse:
+        """Complete a challenge by submitting its solved proof.
+
+        Clears only the bound session, once (anti-replay). Re-verify with
+        ``context={"challengeId": challenge_id}`` so the next verify honors
+        the cleared session.
+        """
+        body: dict[str, Any] = {
+            "eventId": event_id,
+            "challengeId": challenge_id,
+            "proof": proof,
+        }
+        if session is not None:
+            body["session"] = session
+        return cast(
+            ChallengeCompletionResponse,
+            self._request("POST", "/v1/challenge", body=body),
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        headers: dict[str, str] = {}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        try:
+            res = self._http.request(method, path, json=body, headers=headers)
+        except httpx.TimeoutException as exc:
+            raise ChitmarkError(
+                f"Request timed out after {int(self._timeout * 1000)}ms",
+                code="timeout",
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise ChitmarkError(str(exc), code="transport") from exc
+
+        parsed: Any
+        try:
+            parsed = res.json() if res.content else None
+        except ValueError:
+            parsed = res.text
+
+        if res.is_error:
+            raise ChitmarkApiError(res.status_code, parsed)
+
+        return parsed
+
+    @property
+    def config(self) -> dict[str, Any]:
+        return {
+            "base_url": self._base_url,
+            "timeout_ms": int(self._timeout * 1000),
+            "pii_mode": self._pii_mode,
+            "on_degraded": self._on_degraded,
+        }
+
+
+# Re-export Decision for callers
+__all__ += ["Decision"]

chitmark/errors.py

@@ -0,0 +1,45 @@
+"""Chitmark client errors."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ChitmarkError(Exception):
+    """Base error for all Chitmark client failures."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.body = body
+
+
+class ChitmarkApiError(ChitmarkError):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(
+        self,
+        status: int,
+        body: Any,
+        message: str | None = None,
+    ) -> None:
+        if message is None:
+            if isinstance(body, dict):
+                message = str(
+                    body.get("message") or body.get("error") or f"HTTP {status}",
+                )
+            else:
+                message = str(body) or f"HTTP {status}"
+        code = None
+        if isinstance(body, dict):
+            raw = body.get("code") or body.get("error")
+            code = str(raw) if raw is not None else None
+        super().__init__(message, status=status, code=code, body=body)

chitmark/pii.py

@@ -0,0 +1,54 @@
+"""Client-side PII minimization helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Any
+
+
+def hash_email_sha256(email: str) -> str:
+    """SHA-256 hex digest of lowercased, trimmed email."""
+    normalized = email.strip().lower().encode("utf-8")
+    return hashlib.sha256(normalized).hexdigest()
+
+
+def truncate_ip(ip: str) -> str:
+    """Truncate IPv4 to /24 or IPv6 to /48."""
+    first = ip.strip().split(",")[0].strip()
+    if "." in first and ":" not in first:
+        parts = first.split(".")
+        if len(parts) == 4:
+            return f"{parts[0]}.{parts[1]}.{parts[2]}.0/24"
+    if ":" in first:
+        hextets = [h for h in first.split(":") if h]
+        head = ":".join(hextets[:3])
+        return f"{head}::/48"
+    return first
+
+
+_ALLOWED_FORM = {
+    "companyDomain",
+    "company_domain",
+    "domain",
+    "plan",
+    "referrer",
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+}
+
+
+def minimize_form_data(form_data: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Keep only allowed non-PII form keys."""
+    if not form_data:
+        return None
+    out = {k: v for k, v in form_data.items() if k in _ALLOWED_FORM and v is not None}
+    return out or None
+
+
+_EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+
+
+def looks_like_email(value: str) -> bool:
+    return bool(_EMAIL_RE.match(value.strip()))

chitmark/py.typed

@@ -0,0 +1 @@
+# Marker for PEP 561 typed package

chitmark/types.py

@@ -0,0 +1,172 @@
+"""Chitmark Python SDK — type definitions aligned with openapi/openapi.yaml."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+Decision = Literal["allow", "challenge", "deny"]
+ActorType = Literal["human", "agent_principal", "agent_abusive", "unknown"]
+EnforcementMode = Literal["enforce", "log_only"]
+Action = (
+    Literal[
+        "signup",
+        "trial_activation",
+        "api_key",
+        "demo_request",
+        "quote",
+        "ticket",
+        "custom",
+    ]
+    | str
+)
+Outcome = Literal[
+    "credit_burn",
+    "multi_account_cluster",
+    "abuse_confirmed",
+    "converted",
+    "chargeback",
+    "churned",
+    "false_positive",
+]
+ChallengeMethod = Literal[
+    "payment_preauth",
+    "proof_of_work",
+    "device_attestation",
+    "web_bot_auth_stepup",
+    "email_otp",
+]
+PiiMode = Literal["raw", "hashed", "none"]
+ChitmarkEnv = Literal["production", "staging", "development"]
+OnDegraded = Literal["challenge"]
+
+
+class PrincipalRequired(TypedDict):
+    """Required principal fields from verify."""
+    resolved: bool
+    identityBasis: list[str]
+
+
+class Principal(PrincipalRequired, total=False):
+    """Principal resolution from verify."""
+
+    operator: str
+    onBehalfOf: str
+
+
+class Verdict(TypedDict):
+    """Verdict object — single source of truth for a verify call."""
+
+    decision: Decision
+    actorType: ActorType
+    confidence: float
+    reasons: list[str]
+    principal: Principal
+    verdictToken: str
+    eventId: str
+    degraded: bool
+    enforcementMode: EnforcementMode
+
+
+class VerdictTokenClaims(TypedDict, total=False):
+    """Decoded verdictToken JWT payload (see SDK.md §6)."""
+
+    eventId: str
+    decision: Decision
+    actorType: ActorType
+    confidence: float
+    aud: str
+    sub: str
+    jti: str
+    iat: int
+    exp: int
+    degraded: bool
+
+
+class VerdictWithChallenge(Verdict, total=False):
+    """Optional verdict additions for cleared challenges."""
+
+    challengeCleared: bool
+
+
+class Subject(TypedDict, total=False):
+    """Subject signals; prefer hashed fields over raw PII."""
+
+    email: str
+    emailSha256: str
+    ip: str
+    ipTrunc: str
+    userAgent: str
+    headers: dict[str, str]
+    formData: dict[str, Any]
+    formDataHashed: dict[str, Any]
+
+
+class VerifyParams(TypedDict, total=False):
+    """Parameters for Client.verify."""
+
+    idempotency_key: str
+    action: Action
+    session: str
+    surface: str
+    subject: Subject
+    context: dict[str, Any]
+
+
+class FeedbackParams(TypedDict, total=False):
+    """Parameters for Client.feedback."""
+
+    event_id: str
+    outcome: Outcome
+    value: float
+    unit: str
+    observed_at: str
+
+
+class ChallengeParams(TypedDict, total=False):
+    """Parameters for Client.challenge (issue mode)."""
+
+    event_id: str
+    session: str
+    prefer: list[ChallengeMethod]
+
+
+class CompleteChallengeParams(TypedDict, total=False):
+    """Parameters for Client.complete_challenge (completion mode)."""
+
+    event_id: str
+    challenge_id: str
+    session: str
+    proof: ChallengeProof
+
+
+class ProofOfWorkChallengeProof(TypedDict):
+    type: Literal["proof_of_work"]
+    nonce: str
+
+
+class StripeSetupIntentChallengeProof(TypedDict):
+    type: Literal["stripe_setup_intent"]
+    setupIntentId: str
+
+
+ChallengeProof = ProofOfWorkChallengeProof | StripeSetupIntentChallengeProof
+
+
+class FeedbackResponse(TypedDict):
+    ok: bool
+    eventId: str
+
+
+class ChallengeResponse(TypedDict):
+    challengeId: str
+    method: ChallengeMethod
+    instructions: dict[str, Any]
+    boundTo: str
+    expiresAt: str
+
+
+class ChallengeCompletionResponse(TypedDict):
+    ok: bool
+    challengeId: str
+    boundTo: str
+    clearedAt: str

chitmark/verify_token.py

@@ -0,0 +1,228 @@
+"""Client-side verdictToken verification (MVP-016).
+
+A verdictToken is an ES256 JWT decision receipt minted by the edge and bound
+to session (``sub``), origin (``aud``), and ``jti`` with a short ``exp``. This
+module validates shape, signature (against the JWKS served from
+``GET /.well-known/jwks.json``), expiry, session binding, and — when an
+expected audience is supplied — origin binding. Rejection reasons are surfaced
+as ``VerdictTokenError.code``.
+
+Requires the optional extras ``PyJWT`` and ``cryptography``
+(``uv sync --extra verdict``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from chitmark.errors import ChitmarkError
+
+try:  # pragma: no cover - imported lazily; extras are optional
+    import jwt as pyjwt
+    from jwt.exceptions import (
+        DecodeError,
+        ExpiredSignatureError,
+        ImmatureSignatureError,
+        InvalidSignatureError,
+    )
+except ImportError:  # pragma: no cover
+    pyjwt = None  # type: ignore[assignment]
+    DecodeError = ExpiredSignatureError = ImmatureSignatureError = Exception  # type: ignore[misc,assignment]
+    InvalidSignatureError = Exception  # type: ignore[misc,assignment]
+
+
+class VerdictTokenError(ChitmarkError):
+    """Raised when a verdictToken fails verification."""
+
+
+DEFAULT_JWKS_URL = "https://api.chitmark.com/.well-known/jwks.json"
+DEFAULT_LEEWAY_SECONDS = 30
+
+
+def verify_verdict_token(
+    token: str,
+    *,
+    session: str | None = None,
+    aud: str | None = None,
+    jwks: Mapping[str, Any] | None = None,
+    jwks_url: str = DEFAULT_JWKS_URL,
+    http_client: httpx.Client | None = None,
+    leeway_seconds: int = DEFAULT_LEEWAY_SECONDS,
+) -> dict[str, Any]:
+    """Verify a verdictToken signature and binding.
+
+    Args:
+        token: The ES256 JWT from a verify verdict.
+        session: Expected session; token ``sub`` must equal this.
+        aud: Expected origin; token ``aud`` must equal this when provided.
+        jwks: Pre-fetched JWKS mapping; skips the network fetch.
+        jwks_url: JWKS endpoint; defaults to the production API.
+        http_client: Reusable ``httpx.Client`` for the JWKS fetch.
+        leeway_seconds: Clock-skew tolerance.
+
+    Raises:
+        VerdictTokenError: with a machine-readable ``code``:
+            ``malformed_token``, ``wrong_algorithm``, ``jwks_unavailable``,
+            ``unknown_kid``, ``invalid_signature``, ``expired``,
+            ``not_yet_valid``, ``wrong_session``, or ``wrong_aud``.
+    """
+    if pyjwt is None:  # pragma: no cover
+        raise VerdictTokenError(
+            "verdict token verification requires the optional extras "
+            "`PyJWT` and `cryptography` (uv sync --extra verdict)",
+            code="dependency_missing",
+        )
+
+    header = _decode_header(token)
+
+    alg = header.get("alg")
+    if alg != "ES256":
+        raise VerdictTokenError(
+            f"verdictToken must use ES256, got {alg!r}",
+            code="wrong_algorithm",
+        )
+    kid = header.get("kid")
+    if not isinstance(kid, str) or not kid:
+        raise VerdictTokenError(
+            "verdictToken is missing kid",
+            code="unknown_kid",
+        )
+
+    key = _find_jwk(kid, jwks=jwks, jwks_url=jwks_url, http_client=http_client)
+    if key is None:
+        raise VerdictTokenError(
+            f"JWKS has no key for kid {kid}",
+            code="unknown_kid",
+        )
+
+    pem_key = _jwk_to_pem(key)
+    try:
+        claims = pyjwt.decode(
+            token,
+            key=pem_key,
+            algorithms=["ES256"],
+            options={"verify_aud": False},
+            leeway=leeway_seconds,
+        )
+    except ExpiredSignatureError:
+        raise VerdictTokenError(
+            "verdictToken has expired", code="expired"
+        ) from None
+    except ImmatureSignatureError:
+        raise VerdictTokenError(
+            "verdictToken iat is in the future",
+            code="not_yet_valid",
+        ) from None
+    except InvalidSignatureError:
+        raise VerdictTokenError(
+            "verdictToken signature failed verification",
+            code="invalid_signature",
+        ) from None
+    except DecodeError as exc:
+        raise VerdictTokenError(
+            f"verdictToken could not be decoded: {exc}",
+            code="malformed_token",
+        ) from None
+
+    if session is not None and claims.get("sub") != session:
+        raise VerdictTokenError(
+            "verdictToken was minted for a different session",
+            code="wrong_session",
+        )
+    if aud is not None and claims.get("aud") != aud:
+        raise VerdictTokenError(
+            "verdictToken was minted for a different origin",
+            code="wrong_aud",
+        )
+    return claims
+
+
+def _jwk_to_pem(jwk: Mapping[str, Any]) -> bytes:
+    """Convert an EC public JWK (P-256) to a PEM subject-public-key."""
+    import base64
+
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric import ec
+
+    try:
+        x = int.from_bytes(base64.urlsafe_b64decode(jwk["x"] + "=="), "big")
+        y = int.from_bytes(base64.urlsafe_b64decode(jwk["y"] + "=="), "big")
+        public = ec.EllipticCurvePublicNumbers(x, y, ec.SECP256R1()).public_key()
+    except (KeyError, ValueError, TypeError) as exc:
+        raise VerdictTokenError(
+            "JWKS key is not a valid P-256 public key",
+            code="invalid_signature",
+        ) from exc
+    return public.public_bytes(
+        serialization.Encoding.PEM,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+
+
+def _decode_header(token: str) -> dict[str, Any]:
+    try:
+        header = pyjwt.get_unverified_header(token)
+    except Exception as exc:
+        raise VerdictTokenError(
+            f"verdictToken is not a valid JWT: {exc}",
+            code="malformed_token",
+        ) from None
+    if not isinstance(header, dict):
+        raise VerdictTokenError(
+            "verdictToken header is malformed",
+            code="malformed_token",
+        )
+    return header
+
+
+def _find_jwk(
+    kid: str,
+    *,
+    jwks: Mapping[str, Any] | None,
+    jwks_url: str,
+    http_client: httpx.Client | None,
+) -> Mapping[str, Any] | None:
+    if jwks is None:
+        try:
+            client = http_client or httpx.Client(timeout=10.0)
+            owns_client = http_client is None
+            try:
+                res = client.get(jwks_url)
+            finally:
+                if owns_client:
+                    client.close()
+        except httpx.HTTPError as exc:
+            raise VerdictTokenError(
+                f"Failed to load JWKS from {jwks_url}: {exc}",
+                code="jwks_unavailable",
+            ) from None
+        if res.status_code != 200:
+            raise VerdictTokenError(
+                f"Failed to load JWKS from {jwks_url}: HTTP {res.status_code}",
+                code="jwks_unavailable",
+            ) from None
+        try:
+            jwks = res.json()
+        except ValueError as exc:
+            raise VerdictTokenError(
+                f"JWKS response is not JSON: {exc}",
+                code="jwks_unavailable",
+            ) from None
+    if not isinstance(jwks, Mapping):
+        raise VerdictTokenError(
+            "JWKS response has no keys array",
+            code="jwks_unavailable",
+        )
+    keys = jwks.get("keys")
+    if not isinstance(keys, list):
+        raise VerdictTokenError(
+            "JWKS response has no keys array",
+            code="jwks_unavailable",
+        )
+    for key in keys:
+        if isinstance(key, Mapping) and key.get("kid") == kid:
+            return key
+    return None

chitmark-0.1.1.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: chitmark
+Version: 0.1.1
+Summary: Official Python SDK for Chitmark by Open Agent Ledger — trust decisions on agent-mediated actions (verify, feedback, challenge)
+Project-URL: Homepage, https://chitmark.com
+Project-URL: Documentation, https://chitmark.com/docs
+Project-URL: Repository, https://github.com/nonameuserd/Chitmark
+Project-URL: Issues, https://github.com/nonameuserd/Chitmark/issues
+Author-email: Open Agent Ledger <dev@chitmark.com>
+License: Proprietary — no open-source grant. Copyright (c) 2026 Open Agent Ledger. All rights reserved.
+License-File: LICENSE
+Keywords: agent-actions,anti-abuse,chitmark,open-agent-ledger,trust-decisions
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: cryptography>=43.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pyjwt>=2.9.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Provides-Extra: verdict
+Requires-Dist: cryptography>=43.0.0; extra == 'verdict'
+Requires-Dist: pyjwt>=2.9.0; extra == 'verdict'
+Description-Content-Type: text/markdown
+
+# chitmark (Python)
+
+Official Python SDK for Chitmark — trust decisions on agent-mediated actions, tuned by business outcomes (`verify` / `feedback` / `challenge`).
+
+[![PyPI version](https://img.shields.io/pypi/v/chitmark.svg)](https://pypi.org/project/chitmark/)
+
+Requires Python ≥ 3.10.
+
+## Install
+
+```bash
+pip install chitmark
+# or
+uv add chitmark
+```
+
+## Quick start
+
+```python
+from chitmark import Chitmark
+
+client = Chitmark(api_key="ck_live_...")
+
+verdict = client.verify(
+    action="signup",
+    session="sess_9f3a",
+    surface="app.acme.com/signup",
+    subject={
+        "email": "buyer@acmecorp.com",
+        "ip": "203.0.113.7",
+        "userAgent": "...",
+    },
+)
+# Persist verdict["eventId"] on the account row — feedback joins only on that id.
+# Default pii_mode="hashed" minimizes email/IP before the wire.
+```
+
+## API
+
+Three verbs:
+
+| Method                  | Endpoint             | Purpose  |
+| :---------------------- | :------------------- | :------- |
+| `client.verify(...)`    | `POST /v1/verify`    | Decide   |
+| `client.feedback(...)`  | `POST /v1/feedback`  | Learn    |
+| `client.challenge(...)` | `POST /v1/challenge` | Escalate |
+
+**Golden rule:** fail to `challenge`, never to `allow`. Timeouts return a degraded challenge verdict.
+
+### Feedback
+
+Attribution is a schema contract, not a lookup: store the `eventId` from
+`verify` on the account row, then report outcomes against that same id — never
+a derived or guessed id.
+
+```python
+# At signup: persist the join key
+verdict = client.verify(action="signup", subject={"email": "a@b.com"})
+db.accounts.update(user_id, chitmark_event_id=verdict["eventId"])
+
+# Later, when a label matures (credit burn, chargeback, …):
+client.feedback(
+    event_id=account.chitmark_event_id,  # the stored join key — never guessed
+    outcome="credit_burn",
+    value=87.4,
+    unit="usd",
+    observed_at="2026-08-06T04:00:00Z",
+)
+```
+
+### PII
+
+| Mode          | Behavior                                                |
+| :------------ | :------------------------------------------------------ |
+| `hashed` (default) | SHA-256 email, /24 IP truncation, minimized form fields |
+| `none`        | Derived/header-shape signals only                       |
+| `raw`         | Tenant opt-in only; higher compliance review            |
+
+## Develop
+
+```bash
+cd packages/sdk-python
+uv sync --extra dev   # or: pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## Resources
+
+- [API reference](https://chitmark.com/docs)
+- [GitHub](https://github.com/nonameuserd/Chitmark)
+
+## License
+
+Proprietary — see [LICENSE](LICENSE).

chitmark-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+chitmark/__init__.py,sha256=xfaenhYdB5VUHa3v9nmYa-J95Ac7g9a3B_paplYmO8Y,1021
+chitmark/client.py,sha256=XiXcihyd8W-kzAh5yMx2AwIZzsO1dtI5CRzXN4FW-6E,10984
+chitmark/errors.py,sha256=7SW9Bo7GxCOz0TOUejt7iMmU2aAD4iI4KyGJrn70OGQ,1201
+chitmark/pii.py,sha256=uoIMXzE-8TI6H1vS3iYNEJXRs0LzktySZuLkuNpMbnk,1380
+chitmark/py.typed,sha256=gwldFK6aqFdEKlk7Vh3cPNTuEAohX5TTDi8oEN2SqMo,35
+chitmark/types.py,sha256=_KXIyfQF4kr8ALRCEnHDOAcQq2_FdRQpruWUfsZTM1o,3669
+chitmark/verify_token.py,sha256=E3Tmz2LnNpLQVpdqI9S0wEyy3PxhAgdyep-xgS-QtBA,7623
+chitmark-0.1.1.dist-info/METADATA,sha256=W13dWyrhZ6D_QVg5pSuB10LTd8zqMBu1yPczUoVgHyU,4211
+chitmark-0.1.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+chitmark-0.1.1.dist-info/licenses/LICENSE,sha256=Ha5knm4RASNOC0LKQvBeU3cmzHmhrLPaxmncOqkX9kQ,877
+chitmark-0.1.1.dist-info/RECORD,,

chitmark-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

chitmark-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 Open Agent Ledger. All rights reserved.
+
+Proprietary license. You are granted a non-exclusive, non-transferable,
+worldwide right to use, modify, and integrate this software in applications
+that communicate with the Chitmark API. Redistribution of this software or
+its modifications — in whole or in part — and sublicensing are prohibited
+without prior written consent from Open Agent Ledger.
+
+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.