rare-platform-sdk 0.1.0__tar.gz

rare_platform_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: rare-platform-sdk
+Version: 0.1.0
+Summary: Rare platform integration kit for Python services
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://rareid.cc
+Project-URL: Repository, https://github.com/Rare-ID/Rare
+Project-URL: Documentation, https://github.com/Rare-ID/Rare/tree/main/packages/platform/python/rare-platform-sdk-python
+Project-URL: Issues, https://github.com/Rare-ID/Rare/issues
+Keywords: rare,platform,identity,delegation,attestation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rare-identity-protocol>=0.1.0
+Requires-Dist: rare-identity-verifier>=0.1.0
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == "redis"
+Provides-Extra: test
+Requires-Dist: pytest>=8.2.0; extra == "test"
+
+# rare-platform-sdk
+
+Python toolkit for third-party platforms integrating Rare with local verification-first defaults.
+
+## What It Is
+
+`rare-platform-sdk` helps Python services issue Rare auth challenges, complete login, verify delegated signed actions, manage platform sessions, and optionally ingest signed negative-event signals back into Rare.
+
+## Who It Is For
+
+- Python and FastAPI platforms adding Rare login
+- Backend teams that want local identity/delegation verification
+- Integrators that need Redis-backed replay protection and session storage
+
+## Quick Start
+
+```bash
+pip install rare-platform-sdk
+```
+
+```python
+from rare_platform_sdk import (
+    InMemoryChallengeStore,
+    InMemoryReplayStore,
+    InMemorySessionStore,
+    RareApiClient,
+    RarePlatformKitConfig,
+    create_rare_platform_kit,
+)
+
+rare = RareApiClient(rare_base_url="https://api.rareid.cc")
+kit = create_rare_platform_kit(
+    RarePlatformKitConfig(
+        aud="platform",
+        rare_api_client=rare,
+        challenge_store=InMemoryChallengeStore(),
+        replay_store=InMemoryReplayStore(),
+        session_store=InMemorySessionStore(),
+    )
+)
+```
+
+FastAPI integration:
+
+```python
+from fastapi import FastAPI
+from rare_platform_sdk import create_fastapi_rare_router
+
+app = FastAPI()
+app.include_router(create_fastapi_rare_router(kit, prefix="/rare"))
+```
+
+## Production Notes
+
+- Challenge nonces must be one-time use.
+- Delegation replay protection must be atomic.
+- Full identity mode requires `payload.aud == expected_aud`.
+- Identity triad must match:
+  `auth_complete.agent_id == delegation.agent_id == attestation.sub`
+- Public identity mode is capped to `L1` effective governance.
+
+## Development
+
+```bash
+pip install -r requirements-test.lock
+pip install -e .[test] --no-deps
+pytest -q
+python -m build
+```

rare_platform_sdk-0.1.0/README.md

@@ -0,0 +1,69 @@
+# rare-platform-sdk
+
+Python toolkit for third-party platforms integrating Rare with local verification-first defaults.
+
+## What It Is
+
+`rare-platform-sdk` helps Python services issue Rare auth challenges, complete login, verify delegated signed actions, manage platform sessions, and optionally ingest signed negative-event signals back into Rare.
+
+## Who It Is For
+
+- Python and FastAPI platforms adding Rare login
+- Backend teams that want local identity/delegation verification
+- Integrators that need Redis-backed replay protection and session storage
+
+## Quick Start
+
+```bash
+pip install rare-platform-sdk
+```
+
+```python
+from rare_platform_sdk import (
+    InMemoryChallengeStore,
+    InMemoryReplayStore,
+    InMemorySessionStore,
+    RareApiClient,
+    RarePlatformKitConfig,
+    create_rare_platform_kit,
+)
+
+rare = RareApiClient(rare_base_url="https://api.rareid.cc")
+kit = create_rare_platform_kit(
+    RarePlatformKitConfig(
+        aud="platform",
+        rare_api_client=rare,
+        challenge_store=InMemoryChallengeStore(),
+        replay_store=InMemoryReplayStore(),
+        session_store=InMemorySessionStore(),
+    )
+)
+```
+
+FastAPI integration:
+
+```python
+from fastapi import FastAPI
+from rare_platform_sdk import create_fastapi_rare_router
+
+app = FastAPI()
+app.include_router(create_fastapi_rare_router(kit, prefix="/rare"))
+```
+
+## Production Notes
+
+- Challenge nonces must be one-time use.
+- Delegation replay protection must be atomic.
+- Full identity mode requires `payload.aud == expected_aud`.
+- Identity triad must match:
+  `auth_complete.agent_id == delegation.agent_id == attestation.sub`
+- Public identity mode is capped to `L1` effective governance.
+
+## Development
+
+```bash
+pip install -r requirements-test.lock
+pip install -e .[test] --no-deps
+pytest -q
+python -m build
+```

rare_platform_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rare-platform-sdk"
+version = "0.1.0"
+description = "Rare platform integration kit for Python services"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+dependencies = [
+  "fastapi>=0.115.0",
+  "httpx>=0.27.0",
+  "rare-identity-protocol>=0.1.0",
+  "rare-identity-verifier>=0.1.0",
+]
+keywords = ["rare", "platform", "identity", "delegation", "attestation"]
+
+[project.optional-dependencies]
+redis = [
+  "redis>=5.0.0",
+]
+test = [
+  "pytest>=8.2.0",
+]
+
+[project.urls]
+Homepage = "https://rareid.cc"
+Repository = "https://github.com/Rare-ID/Rare"
+Documentation = "https://github.com/Rare-ID/Rare/tree/main/packages/platform/python/rare-platform-sdk-python"
+Issues = "https://github.com/Rare-ID/Rare/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["rare_platform_sdk*"]

rare_platform_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rare_platform_sdk-0.1.0/src/rare_platform_sdk/__init__.py

@@ -0,0 +1,58 @@
+from rare_platform_sdk.client import ApiError, RareApiClient, RareApiClientError
+from rare_platform_sdk.fastapi import (
+    AuthChallengeRequest,
+    AuthChallengeResponse,
+    AuthCompleteRequest,
+    AuthCompleteResponse,
+    create_fastapi_rare_router,
+)
+from rare_platform_sdk.kit import create_rare_platform_kit, sign_platform_event_token
+from rare_platform_sdk.stores import (
+    InMemoryChallengeStore,
+    InMemoryReplayStore,
+    InMemorySessionStore,
+    RedisChallengeStore,
+    RedisReplayStore,
+    RedisSessionStore,
+)
+from rare_platform_sdk.types import (
+    AuthChallenge,
+    AuthCompleteInput,
+    AuthCompleteResult,
+    IngestEventsInput,
+    IngestEventsResult,
+    PlatformSession,
+    RarePlatformEventItem,
+    RarePlatformKitConfig,
+    VerifiedActionContext,
+    VerifyActionInput,
+)
+
+__all__ = [
+    "ApiError",
+    "AuthChallenge",
+    "AuthChallengeRequest",
+    "AuthChallengeResponse",
+    "AuthCompleteInput",
+    "AuthCompleteRequest",
+    "AuthCompleteResponse",
+    "AuthCompleteResult",
+    "InMemoryChallengeStore",
+    "InMemoryReplayStore",
+    "InMemorySessionStore",
+    "IngestEventsInput",
+    "IngestEventsResult",
+    "PlatformSession",
+    "RareApiClient",
+    "RareApiClientError",
+    "RarePlatformEventItem",
+    "RarePlatformKitConfig",
+    "RedisChallengeStore",
+    "RedisReplayStore",
+    "RedisSessionStore",
+    "VerifiedActionContext",
+    "VerifyActionInput",
+    "create_fastapi_rare_router",
+    "create_rare_platform_kit",
+    "sign_platform_event_token",
+]

rare_platform_sdk-0.1.0/src/rare_platform_sdk/client.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+
+class RareApiClientError(RuntimeError):
+    """Raised for Rare API failures."""
+
+
+@dataclass(frozen=True)
+class ApiError(RareApiClientError):
+    status_code: int
+    detail: str
+
+    def __str__(self) -> str:
+        return f"rare api error {self.status_code}: {self.detail}"
+
+
+class RareApiClient:
+    def __init__(
+        self,
+        *,
+        rare_base_url: str,
+        http_client: httpx.AsyncClient | None = None,
+        default_headers: dict[str, str] | None = None,
+        timeout_seconds: float = 10.0,
+    ) -> None:
+        self.rare_base_url = rare_base_url.rstrip("/")
+        self.default_headers = default_headers or {}
+        self._owns_http_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout_seconds)
+
+    async def aclose(self) -> None:
+        if self._owns_http_client:
+            await self._http.aclose()
+
+    async def get_jwks(self) -> dict[str, Any]:
+        return await self._request_json("GET", "/.well-known/rare-keys.json")
+
+    async def issue_platform_register_challenge(
+        self, *, platform_aud: str, domain: str
+    ) -> dict[str, Any]:
+        return await self._request_json(
+            "POST",
+            "/v1/platforms/register/challenge",
+            {"platform_aud": platform_aud, "domain": domain},
+        )
+
+    async def complete_platform_register(
+        self,
+        *,
+        challenge_id: str,
+        platform_id: str,
+        platform_aud: str,
+        domain: str,
+        keys: list[dict[str, str]],
+    ) -> dict[str, Any]:
+        return await self._request_json(
+            "POST",
+            "/v1/platforms/register/complete",
+            {
+                "challenge_id": challenge_id,
+                "platform_id": platform_id,
+                "platform_aud": platform_aud,
+                "domain": domain,
+                "keys": keys,
+            },
+        )
+
+    async def ingest_platform_events(self, event_token: str) -> dict[str, Any]:
+        return await self._request_json(
+            "POST",
+            "/v1/identity-library/events/ingest",
+            {"event_token": event_token},
+        )
+
+    async def _request_json(
+        self, method: str, path: str, body: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        response = await self._http.request(
+            method,
+            f"{self.rare_base_url}{path}",
+            headers={
+                "Content-Type": "application/json",
+                **self.default_headers,
+            },
+            json=body,
+        )
+
+        payload: dict[str, Any] | str
+        try:
+            payload = response.json()
+        except Exception:  # noqa: BLE001
+            payload = response.text
+
+        if response.status_code >= 400:
+            if isinstance(payload, dict):
+                detail = str(payload.get("detail") or payload)
+            else:
+                detail = payload
+            raise ApiError(status_code=response.status_code, detail=detail)
+
+        if not isinstance(payload, dict):
+            raise RareApiClientError("expected JSON object response")
+        return payload

rare_platform_sdk-0.1.0/src/rare_platform_sdk/fastapi.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from rare_identity_protocol import SignatureError, TokenValidationError
+
+from rare_platform_sdk.types import AuthCompleteInput, RarePlatformKit
+
+
+class AuthChallengeRequest(BaseModel):
+    aud: str | None = None
+
+
+class AuthChallengeResponse(BaseModel):
+    nonce: str
+    aud: str
+    issued_at: int
+    expires_at: int
+
+
+class AuthCompleteRequest(BaseModel):
+    nonce: str
+    agent_id: str
+    session_pubkey: str
+    delegation_token: str
+    signature_by_session: str
+    public_identity_attestation: str | None = None
+    full_identity_attestation: str | None = None
+
+
+class AuthCompleteResponse(BaseModel):
+    session_token: str
+    agent_id: str
+    level: str
+    raw_level: str
+    identity_mode: str
+    display_name: str
+    session_pubkey: str
+
+
+def _raise_http(exc: Exception) -> None:
+    if isinstance(exc, PermissionError):
+        raise HTTPException(status_code=401, detail=str(exc)) from exc
+    if isinstance(exc, (TokenValidationError, SignatureError, ValueError)):
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    raise HTTPException(status_code=500, detail="internal server error") from exc
+
+
+def create_fastapi_rare_router(
+    kit: RarePlatformKit, prefix: str = ""
+) -> APIRouter:
+    router = APIRouter(prefix=prefix)
+
+    @router.post("/auth/challenge", response_model=AuthChallengeResponse)
+    async def auth_challenge(request: AuthChallengeRequest) -> AuthChallengeResponse:
+        try:
+            challenge = await kit.issue_challenge(request.aud)
+            return AuthChallengeResponse(**asdict(challenge))
+        except Exception as exc:  # noqa: BLE001
+            _raise_http(exc)
+
+    @router.post("/auth/complete", response_model=AuthCompleteResponse)
+    async def auth_complete(request: AuthCompleteRequest) -> AuthCompleteResponse:
+        try:
+            result = await kit.complete_auth(
+                AuthCompleteInput(
+                    nonce=request.nonce,
+                    agent_id=request.agent_id,
+                    session_pubkey=request.session_pubkey,
+                    delegation_token=request.delegation_token,
+                    signature_by_session=request.signature_by_session,
+                    public_identity_attestation=request.public_identity_attestation,
+                    full_identity_attestation=request.full_identity_attestation,
+                )
+            )
+            return AuthCompleteResponse(**asdict(result))
+        except Exception as exc:  # noqa: BLE001
+            _raise_http(exc)
+
+    return router