orangecheck 0.1.0__py3-none-any.whl

orangecheck/__init__.py

@@ -0,0 +1,60 @@
+"""
+orangecheck — Python SDK for OrangeCheck.
+
+Proof of Bitcoin stake for the open web. A sybil-resistance primitive for
+Django, Flask, FastAPI, or anything on the Python side of the web.
+
+Three load-bearing functions, mirroring the JS SDK:
+
+    from orangecheck import check, verify, discover
+
+    result = check(addr="bc1q...", min_sats=100_000, min_days=30)
+    if result.ok:
+        ...                                      # let them through
+
+All functions are also available on the Client class for configuring a
+custom API base URL, timeouts, or a shared httpx session:
+
+    from orangecheck import Client
+    oc = Client(base_url="https://my-orangecheck.example.com")
+    await oc.check_async(addr="bc1q...", min_sats=100_000)
+"""
+
+from .client import AsyncClient, Client
+from .errors import OrangeCheckError, RateLimitError, VerificationError
+from .top_level import challenge_issue, challenge_verify, check, discover, verify
+from .types import (
+    AttestationSummary,
+    Challenge,
+    ChallengeVerified,
+    CheckResult,
+    DiscoverResult,
+    IdentityBinding,
+    VerifyOutcome,
+)
+
+__all__ = [
+    # Top-level functions (sync)
+    "check",
+    "verify",
+    "discover",
+    "challenge_issue",
+    "challenge_verify",
+    # Clients
+    "Client",
+    "AsyncClient",
+    # Types
+    "CheckResult",
+    "VerifyOutcome",
+    "DiscoverResult",
+    "Challenge",
+    "ChallengeVerified",
+    "IdentityBinding",
+    "AttestationSummary",
+    # Errors
+    "OrangeCheckError",
+    "RateLimitError",
+    "VerificationError",
+]
+
+__version__ = "0.1.0"

orangecheck/__main__.py

@@ -0,0 +1,68 @@
+"""``python -m orangecheck`` — a tiny CLI, mostly for quick sanity checks.
+
+Prefer the TypeScript ``oc`` CLI (``npm install -g @orangecheck/cli``) for
+day-to-day use — it has more features. This one is here so Python users
+can smoke-test the package after ``pip install``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__, check
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="orangecheck", description="OrangeCheck Python SDK")
+    parser.add_argument("--version", action="version", version=f"orangecheck {__version__}")
+
+    sub = parser.add_subparsers(dest="cmd")
+
+    c = sub.add_parser("check", help="Gate on an OrangeCheck proof")
+    c.add_argument("--addr")
+    c.add_argument("--id")
+    c.add_argument("--identity")
+    c.add_argument("--min-sats", type=int, default=0)
+    c.add_argument("--min-days", type=int, default=0)
+    c.add_argument("--base-url", default=None)
+
+    args = parser.parse_args()
+
+    if args.cmd == "check":
+        result = check(
+            addr=args.addr,
+            id=args.id,
+            identity=args.identity,
+            min_sats=args.min_sats,
+            min_days=args.min_days,
+            base_url=args.base_url,
+        )
+        json.dump(
+            {
+                "ok": result.ok,
+                "sats": result.sats,
+                "days": result.days,
+                "score": result.score,
+                "attestation_id": result.attestation_id,
+                "address": result.address,
+                "identities": [
+                    {"protocol": i.protocol, "identifier": i.identifier}
+                    for i in result.identities
+                ],
+                "network": result.network,
+                "reasons": list(result.reasons),
+            },
+            sys.stdout,
+            indent=2,
+        )
+        sys.stdout.write("\n")
+        return 0 if result.ok else 2
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

orangecheck/client.py

@@ -0,0 +1,413 @@
+"""
+Client class for the OrangeCheck Python SDK.
+
+Wraps the hosted ochk.io API. Provides both sync and async variants so
+callers can pick whichever their framework expects.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .errors import OrangeCheckError, RateLimitError, VerificationError
+from .types import (
+    AttestationSummary,
+    Challenge,
+    ChallengeVerified,
+    CheckResult,
+    DiscoverResult,
+    IdentityBinding,
+    VerifyOutcome,
+)
+
+DEFAULT_BASE_URL = "https://ochk.io"
+DEFAULT_TIMEOUT = 10.0
+DEFAULT_UA = "orangecheck-py/0.1.0"
+
+
+def _raise_for_status(status: int, body: Any) -> None:
+    if status == 429:
+        raise RateLimitError("rate limited", status=status, body=body)
+    if status == 404:
+        raise OrangeCheckError("not found", status=status, body=body)
+    if status >= 400:
+        err = "server error"
+        if isinstance(body, dict):
+            err = body.get("error") or body.get("reason") or err
+        raise OrangeCheckError(err, status=status, body=body)
+
+
+class _Common:
+    """Shared helpers for the sync and async clients."""
+
+    def __init__(self, base_url: str = DEFAULT_BASE_URL, *, timeout: float = DEFAULT_TIMEOUT):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    @staticmethod
+    def _check_params(
+        *,
+        addr: str | None,
+        id: str | None,
+        identity: str | IdentityBinding | None,
+        min_sats: int | None,
+        min_days: int | None,
+    ) -> dict[str, str]:
+        if not (addr or id or identity):
+            raise ValueError("must provide addr, id, or identity")
+
+        q: dict[str, str] = {}
+        if addr:
+            q["addr"] = addr
+        elif id:
+            q["id"] = id
+        elif identity:
+            if isinstance(identity, IdentityBinding):
+                q["identity"] = f"{identity.protocol}:{identity.identifier}"
+            else:
+                q["identity"] = identity
+        if min_sats is not None:
+            q["min_sats"] = str(int(min_sats))
+        if min_days is not None:
+            q["min_days"] = str(int(min_days))
+        return q
+
+    @staticmethod
+    def _discover_params(
+        *,
+        addr: str | None,
+        id: str | None,
+        identity: str | IdentityBinding | None,
+        limit: int | None,
+    ) -> dict[str, str]:
+        if not (addr or id or identity):
+            raise ValueError("must provide addr, id, or identity")
+        q: dict[str, str] = {}
+        if addr:
+            q["addr"] = addr
+        elif id:
+            q["id"] = id
+        elif identity:
+            if isinstance(identity, IdentityBinding):
+                q["identity"] = f"{identity.protocol}:{identity.identifier}"
+            else:
+                q["identity"] = identity
+        if limit is not None:
+            q["limit"] = str(int(limit))
+        return q
+
+    @staticmethod
+    def _challenge_params(
+        *,
+        addr: str,
+        audience: str | None,
+        purpose: str | None,
+        ttl: int | None,
+    ) -> dict[str, str]:
+        if not addr:
+            raise ValueError("addr is required")
+        q: dict[str, str] = {"addr": addr}
+        if audience:
+            q["audience"] = audience
+        if purpose:
+            q["purpose"] = purpose
+        if ttl is not None:
+            q["ttl"] = str(int(ttl))
+        return q
+
+    @staticmethod
+    def _headers() -> dict[str, str]:
+        return {"User-Agent": DEFAULT_UA, "Accept": "application/json"}
+
+
+class Client(_Common):
+    """Synchronous OrangeCheck client. One per thread."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        session: httpx.Client | None = None,
+    ):
+        super().__init__(base_url, timeout=timeout)
+        self._session = session or httpx.Client(timeout=timeout, headers=self._headers())
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def _get(self, path: str, params: dict[str, str] | None = None) -> Any:
+        r = self._session.get(f"{self.base_url}{path}", params=params)
+        body: Any
+        try:
+            body = r.json()
+        except ValueError:
+            body = r.text
+        if r.status_code != 200:
+            _raise_for_status(r.status_code, body)
+        return body
+
+    def _post(self, path: str, body: dict[str, Any]) -> Any:
+        r = self._session.post(
+            f"{self.base_url}{path}",
+            json=body,
+            headers={"Content-Type": "application/json"},
+        )
+        try:
+            out = r.json()
+        except ValueError:
+            out = r.text
+        if r.status_code not in (200, 401):
+            _raise_for_status(r.status_code, out)
+        return r.status_code, out
+
+    # --- Public methods ----------------------------------------------------
+
+    def check(
+        self,
+        *,
+        addr: str | None = None,
+        id: str | None = None,
+        identity: str | IdentityBinding | None = None,
+        min_sats: int | None = None,
+        min_days: int | None = None,
+    ) -> CheckResult:
+        """Look up the most recent attestation for a subject and gate it against thresholds."""
+        try:
+            body = self._get("/api/check", self._check_params(
+                addr=addr, id=id, identity=identity, min_sats=min_sats, min_days=min_days
+            ))
+        except OrangeCheckError as e:
+            # /api/check returns 404 when no attestation exists; surface as a
+            # "not found" CheckResult rather than an exception so callers can
+            # gate on result.ok without catching.
+            if e.status == 404 and isinstance(e.body, dict):
+                return CheckResult.from_json({"ok": False, **e.body})
+            raise
+        return CheckResult.from_json(body)
+
+    def verify(
+        self,
+        *,
+        addr: str,
+        msg: str,
+        sig: str,
+        scheme: str = "bip322",
+    ) -> VerifyOutcome:
+        """Verify a raw ``(addr, msg, sig)`` attestation against live chain state."""
+        _, body = self._post(
+            "/api/verify",
+            {"addr": addr, "msg": msg, "sig": sig, "scheme": scheme},
+        )
+        return VerifyOutcome.from_json(body)
+
+    def discover(
+        self,
+        *,
+        addr: str | None = None,
+        id: str | None = None,
+        identity: str | IdentityBinding | None = None,
+        limit: int | None = None,
+    ) -> DiscoverResult:
+        """List attestations known for a subject."""
+        body = self._get("/api/discover", self._discover_params(
+            addr=addr, id=id, identity=identity, limit=limit
+        ))
+        return DiscoverResult.from_json(body)
+
+    def challenge_issue(
+        self,
+        *,
+        addr: str,
+        audience: str | None = None,
+        purpose: str | None = None,
+        ttl: int | None = None,
+    ) -> Challenge:
+        """Mint a short-lived signed-challenge message."""
+        body = self._get(
+            "/api/challenge",
+            self._challenge_params(addr=addr, audience=audience, purpose=purpose, ttl=ttl),
+        )
+        return Challenge.from_json(body)
+
+    def challenge_verify(
+        self,
+        *,
+        message: str,
+        signature: str,
+        scheme: str = "bip322",
+        expected_nonce: str | None = None,
+        expected_audience: str | None = None,
+        expected_purpose: str | None = None,
+    ) -> ChallengeVerified:
+        """Verify a signed challenge. Raises :class:`VerificationError` on failure."""
+        body: dict[str, Any] = {
+            "message": message,
+            "signature": signature,
+            "scheme": scheme,
+        }
+        if expected_nonce:
+            body["expectedNonce"] = expected_nonce
+        if expected_audience:
+            body["expectedAudience"] = expected_audience
+        if expected_purpose:
+            body["expectedPurpose"] = expected_purpose
+
+        status, resp = self._post("/api/challenge", body)
+        if status == 200 and isinstance(resp, dict) and resp.get("ok"):
+            return ChallengeVerified.from_json(resp)
+        reason = resp.get("reason") if isinstance(resp, dict) else "unknown"
+        raise VerificationError(
+            f"challenge verification failed: {reason}", status=status, body=resp
+        )
+
+
+class AsyncClient(_Common):
+    """Async variant. One per event loop."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        session: httpx.AsyncClient | None = None,
+    ):
+        super().__init__(base_url, timeout=timeout)
+        self._session = session or httpx.AsyncClient(
+            timeout=timeout, headers=self._headers()
+        )
+
+    async def aclose(self) -> None:
+        await self._session.aclose()
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    async def _get(self, path: str, params: dict[str, str] | None = None) -> Any:
+        r = await self._session.get(f"{self.base_url}{path}", params=params)
+        try:
+            body = r.json()
+        except ValueError:
+            body = r.text
+        if r.status_code != 200:
+            _raise_for_status(r.status_code, body)
+        return body
+
+    async def _post(self, path: str, body: dict[str, Any]) -> Any:
+        r = await self._session.post(
+            f"{self.base_url}{path}",
+            json=body,
+            headers={"Content-Type": "application/json"},
+        )
+        try:
+            out = r.json()
+        except ValueError:
+            out = r.text
+        if r.status_code not in (200, 401):
+            _raise_for_status(r.status_code, out)
+        return r.status_code, out
+
+    async def check(
+        self,
+        *,
+        addr: str | None = None,
+        id: str | None = None,
+        identity: str | IdentityBinding | None = None,
+        min_sats: int | None = None,
+        min_days: int | None = None,
+    ) -> CheckResult:
+        try:
+            body = await self._get("/api/check", self._check_params(
+                addr=addr, id=id, identity=identity, min_sats=min_sats, min_days=min_days
+            ))
+        except OrangeCheckError as e:
+            if e.status == 404 and isinstance(e.body, dict):
+                return CheckResult.from_json({"ok": False, **e.body})
+            raise
+        return CheckResult.from_json(body)
+
+    async def verify(
+        self,
+        *,
+        addr: str,
+        msg: str,
+        sig: str,
+        scheme: str = "bip322",
+    ) -> VerifyOutcome:
+        _, body = await self._post(
+            "/api/verify", {"addr": addr, "msg": msg, "sig": sig, "scheme": scheme}
+        )
+        return VerifyOutcome.from_json(body)
+
+    async def discover(
+        self,
+        *,
+        addr: str | None = None,
+        id: str | None = None,
+        identity: str | IdentityBinding | None = None,
+        limit: int | None = None,
+    ) -> DiscoverResult:
+        body = await self._get("/api/discover", self._discover_params(
+            addr=addr, id=id, identity=identity, limit=limit
+        ))
+        return DiscoverResult.from_json(body)
+
+    async def challenge_issue(
+        self,
+        *,
+        addr: str,
+        audience: str | None = None,
+        purpose: str | None = None,
+        ttl: int | None = None,
+    ) -> Challenge:
+        body = await self._get(
+            "/api/challenge",
+            self._challenge_params(addr=addr, audience=audience, purpose=purpose, ttl=ttl),
+        )
+        return Challenge.from_json(body)
+
+    async def challenge_verify(
+        self,
+        *,
+        message: str,
+        signature: str,
+        scheme: str = "bip322",
+        expected_nonce: str | None = None,
+        expected_audience: str | None = None,
+        expected_purpose: str | None = None,
+    ) -> ChallengeVerified:
+        body: dict[str, Any] = {
+            "message": message,
+            "signature": signature,
+            "scheme": scheme,
+        }
+        if expected_nonce:
+            body["expectedNonce"] = expected_nonce
+        if expected_audience:
+            body["expectedAudience"] = expected_audience
+        if expected_purpose:
+            body["expectedPurpose"] = expected_purpose
+
+        status, resp = await self._post("/api/challenge", body)
+        if status == 200 and isinstance(resp, dict) and resp.get("ok"):
+            return ChallengeVerified.from_json(resp)
+        reason = resp.get("reason") if isinstance(resp, dict) else "unknown"
+        raise VerificationError(
+            f"challenge verification failed: {reason}", status=status, body=resp
+        )
+
+
+# Make the classes accessible under an unused-name alias so `AttestationSummary`
+# shows up in the type stubs generated from this module.
+_ = AttestationSummary

orangecheck/errors.py

@@ -0,0 +1,20 @@
+"""Exception hierarchy for the OrangeCheck Python SDK."""
+
+from __future__ import annotations
+
+
+class OrangeCheckError(Exception):
+    """Base class for every error raised by this SDK."""
+
+    def __init__(self, message: str, *, status: int | None = None, body: object | None = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class RateLimitError(OrangeCheckError):
+    """Returned by the hosted API when the caller hits its rate limit."""
+
+
+class VerificationError(OrangeCheckError):
+    """Raised by verify_challenge when the signature or nonce doesn't match."""

orangecheck/top_level.py

@@ -0,0 +1,101 @@
+"""
+Module-level convenience wrappers.
+
+Most callers don't need a dedicated Client instance — they just want::
+
+    from orangecheck import check
+    result = check(addr="bc1q...", min_sats=100_000)
+
+Each of these functions spins up a default ``Client`` under the hood. For
+long-running apps that care about connection reuse, make your own ``Client``.
+"""
+
+from __future__ import annotations
+
+from .client import Client
+from .types import (
+    Challenge,
+    ChallengeVerified,
+    CheckResult,
+    DiscoverResult,
+    IdentityBinding,
+    VerifyOutcome,
+)
+
+
+def check(
+    *,
+    addr: str | None = None,
+    id: str | None = None,
+    identity: str | IdentityBinding | None = None,
+    min_sats: int | None = None,
+    min_days: int | None = None,
+    base_url: str | None = None,
+) -> CheckResult:
+    with _client(base_url) as c:
+        return c.check(
+            addr=addr, id=id, identity=identity, min_sats=min_sats, min_days=min_days
+        )
+
+
+def verify(
+    *,
+    addr: str,
+    msg: str,
+    sig: str,
+    scheme: str = "bip322",
+    base_url: str | None = None,
+) -> VerifyOutcome:
+    with _client(base_url) as c:
+        return c.verify(addr=addr, msg=msg, sig=sig, scheme=scheme)
+
+
+def discover(
+    *,
+    addr: str | None = None,
+    id: str | None = None,
+    identity: str | IdentityBinding | None = None,
+    limit: int | None = None,
+    base_url: str | None = None,
+) -> DiscoverResult:
+    with _client(base_url) as c:
+        return c.discover(addr=addr, id=id, identity=identity, limit=limit)
+
+
+def challenge_issue(
+    *,
+    addr: str,
+    audience: str | None = None,
+    purpose: str | None = None,
+    ttl: int | None = None,
+    base_url: str | None = None,
+) -> Challenge:
+    with _client(base_url) as c:
+        return c.challenge_issue(addr=addr, audience=audience, purpose=purpose, ttl=ttl)
+
+
+def challenge_verify(
+    *,
+    message: str,
+    signature: str,
+    scheme: str = "bip322",
+    expected_nonce: str | None = None,
+    expected_audience: str | None = None,
+    expected_purpose: str | None = None,
+    base_url: str | None = None,
+) -> ChallengeVerified:
+    with _client(base_url) as c:
+        return c.challenge_verify(
+            message=message,
+            signature=signature,
+            scheme=scheme,
+            expected_nonce=expected_nonce,
+            expected_audience=expected_audience,
+            expected_purpose=expected_purpose,
+        )
+
+
+def _client(base_url: str | None) -> Client:
+    if base_url:
+        return Client(base_url=base_url)
+    return Client()

orangecheck/types.py

@@ -0,0 +1,169 @@
+"""Typed data classes for the OrangeCheck Python SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+
+@dataclass(frozen=True)
+class IdentityBinding:
+    """A self-asserted handle bound to a Bitcoin address."""
+
+    protocol: str
+    identifier: str
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """The shape returned by :func:`check`."""
+
+    ok: bool
+    sats: int
+    days: int
+    score: float
+    attestation_id: str | None = None
+    address: str | None = None
+    identities: tuple[IdentityBinding, ...] = field(default_factory=tuple)
+    network: Literal["mainnet", "testnet", "signet"] | None = None
+    reasons: tuple[str, ...] = field(default_factory=tuple)
+
+    @classmethod
+    def from_json(cls, d: dict[str, Any]) -> "CheckResult":
+        ids = tuple(
+            IdentityBinding(protocol=i["protocol"], identifier=i["identifier"])
+            for i in d.get("identities") or []
+        )
+        return cls(
+            ok=bool(d["ok"]),
+            sats=int(d.get("sats", 0)),
+            days=int(d.get("days", 0)),
+            score=float(d.get("score", 0)),
+            attestation_id=d.get("attestation_id"),
+            address=d.get("address"),
+            identities=ids,
+            network=d.get("network"),
+            reasons=tuple(d.get("reasons") or ()),
+        )
+
+
+@dataclass(frozen=True)
+class VerifyOutcome:
+    """The shape returned by :func:`verify`."""
+
+    ok: bool
+    codes: tuple[str, ...]
+    network: Literal["mainnet", "testnet", "signet"]
+    attestation_id: str | None = None
+    identities: tuple[IdentityBinding, ...] = field(default_factory=tuple)
+    sats_bonded: int | None = None
+    days_unspent: int | None = None
+    score: float | None = None
+
+    @classmethod
+    def from_json(cls, d: dict[str, Any]) -> "VerifyOutcome":
+        metrics = d.get("metrics") or {}
+        ids = tuple(
+            IdentityBinding(protocol=i["protocol"], identifier=i["identifier"])
+            for i in d.get("identities") or []
+        )
+        return cls(
+            ok=bool(d["ok"]),
+            codes=tuple(d.get("codes") or ()),
+            network=d.get("network", "mainnet"),
+            attestation_id=d.get("attestation_id"),
+            identities=ids,
+            sats_bonded=metrics.get("sats_bonded"),
+            days_unspent=metrics.get("days_unspent"),
+            score=metrics.get("score"),
+        )
+
+
+@dataclass(frozen=True)
+class AttestationSummary:
+    """A single entry from a :func:`discover` response."""
+
+    attestation_id: str
+    address: str
+    scheme: str
+    identities: tuple[IdentityBinding, ...]
+    issued_at: str
+    expires_at: str | None = None
+    verification_url: str | None = None
+    relay_hints: tuple[str, ...] = field(default_factory=tuple)
+
+    @classmethod
+    def from_json(cls, d: dict[str, Any]) -> "AttestationSummary":
+        ids = tuple(
+            IdentityBinding(protocol=i["protocol"], identifier=i["identifier"])
+            for i in d.get("identities") or []
+        )
+        return cls(
+            attestation_id=d["attestation_id"],
+            address=d["address"],
+            scheme=d.get("scheme", "bip322"),
+            identities=ids,
+            issued_at=d.get("issued_at", ""),
+            expires_at=d.get("expires_at"),
+            verification_url=d.get("verification_url"),
+            relay_hints=tuple(d.get("relay_hints") or ()),
+        )
+
+
+@dataclass(frozen=True)
+class DiscoverResult:
+    """The shape returned by :func:`discover`."""
+
+    count: int
+    total: int
+    attestations: tuple[AttestationSummary, ...]
+
+    @classmethod
+    def from_json(cls, d: dict[str, Any]) -> "DiscoverResult":
+        return cls(
+            count=int(d.get("count", 0)),
+            total=int(d.get("total", 0)),
+            attestations=tuple(
+                AttestationSummary.from_json(a) for a in d.get("attestations") or ()
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class Challenge:
+    """Response shape from ``GET /api/challenge``."""
+
+    message: str
+    nonce: str
+    expires_at: int
+    expires_at_iso: str
+
+    @classmethod
+    def from_json(cls, d: dict[str, Any]) -> "Challenge":
+        return cls(
+            message=d["message"],
+            nonce=d["nonce"],
+            expires_at=int(d["expiresAt"]),
+            expires_at_iso=d.get("expiresAtIso", ""),
+        )
+
+
+@dataclass(frozen=True)
+class ChallengeVerified:
+    """Successful response shape from ``POST /api/challenge``."""
+
+    address: str
+    nonce: str
+    expires_at: int
+    audience: str | None = None
+    purpose: str | None = None
+
+    @classmethod
+    def from_json(cls, d: dict[str, Any]) -> "ChallengeVerified":
+        return cls(
+            address=d["address"],
+            nonce=d["nonce"],
+            expires_at=int(d["expiresAt"]),
+            audience=d.get("audience"),
+            purpose=d.get("purpose"),
+        )

orangecheck-0.1.0.dist-info/METADATA

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: orangecheck
+Version: 0.1.0
+Summary: Python SDK for OrangeCheck — proof of Bitcoin stake for the open web.
+Project-URL: Homepage, https://ochk.io
+Project-URL: Documentation, https://ochk.io/docs
+Project-URL: Repository, https://github.com/orangecheck/oc-web
+Project-URL: Issues, https://github.com/orangecheck/oc-web/issues
+Author: OrangeCheck
+License: MIT
+Keywords: attestation,bip322,bitcoin,nostr,orangecheck,sybil-resistance
+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.9
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# `orangecheck` — Python SDK
+
+**Proof of Bitcoin stake for the open web.** Python SDK for OrangeCheck.
+
+A sybil-resistance primitive any Python app can consume in one call. Works with Django, Flask, FastAPI, Starlette, or a plain script.
+
+```bash
+pip install orangecheck
+```
+
+---
+
+## The 30-second integration
+
+```python
+from orangecheck import check
+
+result = check(addr="bc1q...", min_sats=100_000, min_days=30)
+
+if result.ok:
+    # let them through
+    ...
+else:
+    print("rejected:", result.reasons)
+```
+
+That's it. `check()` queries the hosted `ochk.io` API, which discovers the most recent attestation for the address on Nostr, verifies the Bitcoin signature, recomputes live chain state, and compares against your thresholds.
+
+---
+
+## Load-bearing functions
+
+```python
+from orangecheck import check, verify, discover, challenge_issue, challenge_verify
+
+# Gate
+check(addr="bc1q...", min_sats=100_000, min_days=30)
+check(id="a3f5b8c2...", min_sats=100_000)
+check(identity="github:alice", min_sats=50_000)
+
+# Verify a raw attestation
+verify(addr="bc1q...", msg=canonical_message, sig=signature)
+
+# List attestations for a subject
+discover(addr="bc1q...", limit=10)
+
+# Signed-challenge auth (prove address control)
+ch       = challenge_issue(addr="bc1q...", audience="https://example.com")
+verified = challenge_verify(message=ch.message, signature=user_sig, expected_nonce=ch.nonce)
+```
+
+All return typed dataclasses. All raise `OrangeCheckError` (or subclasses) on transport / server errors.
+
+---
+
+## Django integration
+
+```python
+# views.py
+from django.http import HttpResponse, JsonResponse
+from orangecheck import check
+
+def gated_post(request):
+    addr = request.session.get("btc_address")
+    if not addr:
+        return HttpResponse(status=401)
+    result = check(addr=addr, min_sats=100_000, min_days=30)
+    if not result.ok:
+        return JsonResponse({"error": "orangecheck", "reasons": result.reasons}, status=403)
+    # ... proceed
+    return JsonResponse({"ok": True})
+```
+
+### As middleware
+
+```python
+# orangecheck_middleware.py
+from django.http import JsonResponse
+from orangecheck import check
+
+class OrangeCheckMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        if request.path.startswith("/protected/"):
+            addr = request.session.get("btc_address")
+            r = check(addr=addr, min_sats=100_000, min_days=30)
+            if not r.ok:
+                return JsonResponse({"error": r.reasons}, status=403)
+        return self.get_response(request)
+```
+
+---
+
+## FastAPI integration
+
+```python
+from fastapi import FastAPI, Depends, HTTPException
+from orangecheck import AsyncClient
+
+app = FastAPI()
+oc  = AsyncClient()
+
+async def require_stake(addr: str, min_sats: int = 100_000, min_days: int = 30):
+    r = await oc.check(addr=addr, min_sats=min_sats, min_days=min_days)
+    if not r.ok:
+        raise HTTPException(status_code=403, detail={"reasons": list(r.reasons)})
+    return r
+
+@app.post("/post")
+async def post_comment(gate = Depends(require_stake)):
+    return {"ok": True, "sats": gate.sats}
+```
+
+---
+
+## Flask integration
+
+```python
+from functools import wraps
+from flask import Flask, request, jsonify
+from orangecheck import check
+
+app = Flask(__name__)
+
+def require_orangecheck(min_sats=100_000, min_days=30):
+    def decorator(fn):
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            addr = request.headers.get("X-OC-Address")
+            r = check(addr=addr, min_sats=min_sats, min_days=min_days)
+            if not r.ok:
+                return jsonify(error="orangecheck", reasons=r.reasons), 403
+            return fn(*args, **kwargs)
+        return wrapper
+    return decorator
+
+@app.post("/post")
+@require_orangecheck(min_sats=100_000, min_days=30)
+def post_comment():
+    return {"ok": True}
+```
+
+---
+
+## Async
+
+Every function has a sync counterpart on `AsyncClient`:
+
+```python
+import asyncio
+from orangecheck import AsyncClient
+
+async def main():
+    async with AsyncClient() as oc:
+        r = await oc.check(addr="bc1q...", min_sats=100_000)
+        print(r.ok, r.sats, r.days)
+
+asyncio.run(main())
+```
+
+---
+
+## Configuration
+
+```python
+from orangecheck import Client
+
+# Default — hits https://ochk.io
+c = Client()
+
+# Self-hosted verifier, custom timeout
+c = Client(base_url="https://verifier.mycompany.com", timeout=5.0)
+
+# Reuse an existing httpx Client (connection pooling, auth, etc.)
+import httpx
+my_session = httpx.Client(proxies="http://proxy.example.com")
+c = Client(session=my_session)
+```
+
+---
+
+## Types
+
+Every response is a frozen `dataclass` with predictable fields:
+
+```python
+@dataclass(frozen=True)
+class CheckResult:
+    ok: bool
+    sats: int
+    days: int
+    score: float
+    attestation_id: str | None
+    address: str | None
+    identities: tuple[IdentityBinding, ...]
+    network: Literal["mainnet", "testnet", "signet"] | None
+    reasons: tuple[str, ...]
+```
+
+Full type information ships with the package (`py.typed` marker, tested with mypy strict).
+
+---
+
+## Errors
+
+- **`OrangeCheckError`** — base class for everything else.
+- **`RateLimitError`** — the hosted API returned 429.
+- **`VerificationError`** — `challenge_verify` failed (bad signature, expired, nonce mismatch, …).
+
+`check()` treats 404 (no attestation found) as `CheckResult(ok=False, reasons=("not_found",))` rather than raising — callers should gate on `.ok`, not on try/except.
+
+---
+
+## Shell smoke-test
+
+```bash
+python -m orangecheck check --addr bc1q... --min-sats 100000
+```
+
+Exits `0` on pass, `2` on fail. Prefer the TypeScript `oc` CLI for richer output; this one is here mostly to verify the install.
+
+---
+
+## License
+
+MIT. The OrangeCheck protocol is CC-BY-4.0.

orangecheck-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+orangecheck/__init__.py,sha256=-IF763Cbydc4v1occEk2ANezCMS86jBGICxdsdmm5pI,1555
+orangecheck/__main__.py,sha256=h8qj5Ok8NFU1z-TLsqLI_A_Y_VkqF8C26UQ_xb1PpbE,2027
+orangecheck/client.py,sha256=qA-hrLr5NlNtDX0GoaI3VyKfRbua1_V426BqlaiLwZA,12962
+orangecheck/errors.py,sha256=WI8tbTtge8UGkGB5NrjSLo-Q5RaqwcIxuJWVrPQVt1A,614
+orangecheck/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+orangecheck/top_level.py,sha256=TYlbG7TOFeIweHAsDnA5mSRR_q7C_oh6a9CFJ9bzU4Q,2542
+orangecheck/types.py,sha256=uCgo3UDNRrJLbZOvMLJx2WEOqv8ND7feCS1_kuZSsqk,4914
+orangecheck-0.1.0.dist-info/METADATA,sha256=mNxjRy4xJ81LgsjasVQXN0T4Kr0Hhe0zqk9HzRQ_rRo,7066
+orangecheck-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+orangecheck-0.1.0.dist-info/entry_points.txt,sha256=UbQiJ3mKP-WqYB_gHTM4JZSkoWnaLQSCeJQj5ssst_E,58
+orangecheck-0.1.0.dist-info/RECORD,,

orangecheck-0.1.0.dist-info/WHEEL

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

orangecheck-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+orangecheck = orangecheck.__main__:main