cred-auth 1.0.0__tar.gz

cred_auth-1.0.0/.gitignore

@@ -0,0 +1,50 @@
+node_modules/
+dist/
+build/
+
+# Sprint artifacts
+.factory/
+.sprint-*
+.sprint-pid
+.rewire-done
+.content-rewrite-done
+.hubspot-done
+.integrations-done
+.done
+.validation-report.md
+.sprint-logs/
+.sprint-prompts/
+SESSION_PACKAGE.md
+run-sprint.sh
+validate.sh
+
+# Internal planning docs (not for public repo)
+CLAUDE.md
+PLAN.md
+HANDOFF.md
+VALIDATION.md
+MARKETING-VALIDATION.md
+FINAL-SUBMISSION-VALIDATION.md
+.next/
+out/
+coverage/
+*.tsbuildinfo
+.turbo/
+.DS_Store
+*.pem
+.env
+.env.local
+.env*.local
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+.pytest_cache/
+.venv/
+venv/
+dist/
+*.dist-info/
+packages/sdk-python/.venv/

cred_auth-1.0.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: cred-auth
+Version: 1.0.0
+Summary: Cred — credential delegation SDK for AI agents
+Project-URL: Homepage, https://cred.ninja
+Project-URL: Repository, https://github.com/cred-ninja/sdk
+Project-URL: Documentation, https://docs.cred.ninja
+Author-email: Cred <hello@cred.ninja>
+License: Apache-2.0
+Keywords: ai-agents,cred,credentials,delegation,oauth
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software 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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cred-auth
+
+Python SDK for Cred. OAuth2 credential delegation for AI agents. Tokens are brokered, never exposed.
+
+## Install
+
+```bash
+pip install cred-auth
+```
+
+## Quick Start
+
+```python
+import os
+from cred import Cred, ConsentRequiredError
+
+cred = Cred(agent_token=os.environ["CRED_AGENT_TOKEN"])
+
+try:
+    result = cred.delegate(
+        service="google",
+        user_id="user_123",
+        app_client_id="my_app_client_id",
+        scopes=["calendar.readonly"],
+    )
+    print(result.access_token)
+except ConsentRequiredError as e:
+    # Redirect user to e.consent_url to complete OAuth consent
+    print(f"Redirect user to: {e.consent_url}")
+```
+
+## API
+
+### `Cred(agent_token, base_url=...)`
+
+### `delegate(service, user_id, app_client_id, scopes=None) → DelegationResult`
+
+Get a delegated access token for a service on behalf of a user.
+
+Raises `ConsentRequiredError` (with `.consent_url`) if the user hasn't connected the service.
+
+### `get_user_connections(user_id, app_client_id=None) → list[Connection]`
+
+List all active service connections for a user.
+
+### `get_consent_url(service, user_id, app_client_id, scopes, redirect_uri) → str`
+
+Build a consent URL. Pure URL construction, no HTTP call.
+
+### `revoke(service, user_id, app_client_id=None) → None`
+
+Revoke a user's connection to a service.
+
+## Context Manager
+
+```python
+with Cred(agent_token=token) as cred:
+    result = cred.delegate(service="github", user_id="u1", app_client_id="app1")
+```
+
+## Self-Hosted Server Mode
+
+Point `base_url` at your own `@credninja/server` deployment when you want a separate credential broker instead of local-only usage.

cred_auth-1.0.0/README.md

@@ -0,0 +1,63 @@
+# cred-auth
+
+Python SDK for Cred. OAuth2 credential delegation for AI agents. Tokens are brokered, never exposed.
+
+## Install
+
+```bash
+pip install cred-auth
+```
+
+## Quick Start
+
+```python
+import os
+from cred import Cred, ConsentRequiredError
+
+cred = Cred(agent_token=os.environ["CRED_AGENT_TOKEN"])
+
+try:
+    result = cred.delegate(
+        service="google",
+        user_id="user_123",
+        app_client_id="my_app_client_id",
+        scopes=["calendar.readonly"],
+    )
+    print(result.access_token)
+except ConsentRequiredError as e:
+    # Redirect user to e.consent_url to complete OAuth consent
+    print(f"Redirect user to: {e.consent_url}")
+```
+
+## API
+
+### `Cred(agent_token, base_url=...)`
+
+### `delegate(service, user_id, app_client_id, scopes=None) → DelegationResult`
+
+Get a delegated access token for a service on behalf of a user.
+
+Raises `ConsentRequiredError` (with `.consent_url`) if the user hasn't connected the service.
+
+### `get_user_connections(user_id, app_client_id=None) → list[Connection]`
+
+List all active service connections for a user.
+
+### `get_consent_url(service, user_id, app_client_id, scopes, redirect_uri) → str`
+
+Build a consent URL. Pure URL construction, no HTTP call.
+
+### `revoke(service, user_id, app_client_id=None) → None`
+
+Revoke a user's connection to a service.
+
+## Context Manager
+
+```python
+with Cred(agent_token=token) as cred:
+    result = cred.delegate(service="github", user_id="u1", app_client_id="app1")
+```
+
+## Self-Hosted Server Mode
+
+Point `base_url` at your own `@credninja/server` deployment when you want a separate credential broker instead of local-only usage.

cred_auth-1.0.0/cred/__init__.py

@@ -0,0 +1,33 @@
+"""Cred — credential delegation SDK for AI agents."""
+
+from .client import AsyncCred, Cred
+from .exceptions import (
+    AgentRevokedException,
+    ConsentRequiredError,
+    CredError,
+    RateLimitException,
+    ScopeCeilingException,
+)
+from .identity import (
+    AgentIdentity,
+    CRED_PUBLIC_KEY_HEX,
+    generate_agent_identity,
+    verify_delegation_receipt,
+)
+from .models import DelegationResult, Connection
+
+__all__ = [
+    "Cred",
+    "AsyncCred",
+    "CredError",
+    "ConsentRequiredError",
+    "AgentRevokedException",
+    "ScopeCeilingException",
+    "RateLimitException",
+    "AgentIdentity",
+    "generate_agent_identity",
+    "verify_delegation_receipt",
+    "CRED_PUBLIC_KEY_HEX",
+    "DelegationResult",
+    "Connection",
+]

cred_auth-1.0.0/cred/client.py

@@ -0,0 +1,335 @@
+"""Cred SDK — Main client classes."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional
+from urllib.parse import urlencode, urlparse
+
+import httpx
+
+from .exceptions import (
+    AgentRevokedException,
+    ConsentRequiredError,
+    CredError,
+    RateLimitException,
+    ScopeCeilingException,
+)
+from .models import Connection, DelegationResult
+
+DEFAULT_BASE_URL = "https://api.cred.ninja"
+_LOCALHOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+def _parse_expires_at(raw_value: Any, expires_in: int) -> datetime:
+    if isinstance(raw_value, str):
+        parsed_value = raw_value.replace("Z", "+00:00")
+        try:
+            return datetime.fromisoformat(parsed_value)
+        except ValueError:
+            pass
+    return datetime.now(timezone.utc) + timedelta(seconds=expires_in)
+
+
+class _CredBase:
+    def __init__(self, agent_token: str, base_url: str = DEFAULT_BASE_URL) -> None:
+        if not agent_token:
+            raise CredError("agent_token is required", "invalid_config", 0)
+        self._agent_token = agent_token
+        self._base_url = self._validate_base_url(base_url)
+
+    @staticmethod
+    def _validate_base_url(url: str) -> str:
+        try:
+            parsed = urlparse(url)
+        except Exception:
+            raise CredError(f'Invalid base_url: "{url}" — must be a valid HTTPS URL', "invalid_config", 0)
+
+        if parsed.scheme == "https":
+            return url.rstrip("/")
+
+        if parsed.scheme == "http" and parsed.hostname in _LOCALHOSTS:
+            return url.rstrip("/")
+
+        raise CredError(
+            "Invalid base_url: must use HTTPS except for localhost development URLs",
+            "invalid_config",
+            0,
+        )
+
+    def _auth_headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._agent_token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+
+    @staticmethod
+    def _build_delegation_result(data: dict[str, Any]) -> DelegationResult:
+        raw_expires_in = data.get("expires_in")
+        expires_in = int(raw_expires_in) if raw_expires_in is not None else 900
+        expires_at = _parse_expires_at(data.get("expires_at") or data.get("expiresAt"), expires_in)
+        return DelegationResult(
+            access_token=data["access_token"],
+            token_type=data["token_type"],
+            expires_in=expires_in,
+            expires_at=expires_at,
+            service=data["service"],
+            scopes=data["scopes"],
+            delegation_id=data["delegation_id"],
+            receipt=data.get("receipt"),
+        )
+
+    @staticmethod
+    def _build_connections(data: dict[str, Any]) -> list[Connection]:
+        connections = data.get("connections", [])
+        return [
+            Connection(
+                slug=connection["slug"],
+                scopes_granted=connection["scopesGranted"],
+                app_client_id=connection.get("appClientId"),
+                consented_at=connection.get("consentedAt"),
+            )
+            for connection in connections
+        ]
+
+    @staticmethod
+    def _error_payload(response: httpx.Response) -> tuple[dict[str, Any], str, str]:
+        body: dict[str, Any] = {}
+        try:
+            parsed = response.json()
+            if isinstance(parsed, dict):
+                body = parsed
+        except Exception:
+            pass
+
+        message = body.get("message") or body.get("error") or f"Request failed with status {response.status_code}"
+        error_code = str(body.get("error", "unknown"))
+        return body, str(message), error_code
+
+    def _handle_response(self, response: httpx.Response) -> Any:
+        if response.status_code == 204:
+            return {}
+
+        if response.is_success:
+            return response.json()
+
+        body, message, error_code = self._error_payload(response)
+
+        if response.status_code == 403 and error_code == "consent_required":
+            raise ConsentRequiredError(message, str(body.get("consent_url", "")))
+        if response.status_code == 403 and error_code == "agent_revoked":
+            raise AgentRevokedException(message)
+        if response.status_code == 403 and error_code == "scope_ceiling_exceeded":
+            raise ScopeCeilingException(message)
+        if response.status_code == 429 and error_code == "rate_limited":
+            raise RateLimitException(message)
+
+        raise CredError(message, error_code, response.status_code)
+
+    def get_consent_url(
+        self,
+        service: str,
+        user_id: str,
+        app_client_id: str,
+        scopes: list[str],
+        redirect_uri: str,
+    ) -> str:
+        params = urlencode(
+            {
+                "app_client_id": app_client_id,
+                "scopes": ",".join(scopes),
+                "redirect_uri": redirect_uri,
+            },
+        )
+        return f"{self._base_url}/api/connect/{service}/authorize?{params}"
+
+
+class Cred(_CredBase):
+    """Synchronous client for the Cred credential delegation API."""
+
+    def __init__(
+        self,
+        agent_token: str,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> None:
+        super().__init__(agent_token=agent_token, base_url=base_url)
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers=self._auth_headers(),
+            timeout=30.0,
+        )
+
+    def delegate(
+        self,
+        service: str,
+        user_id: str,
+        app_client_id: Optional[str] = None,
+        scopes: Optional[list[str]] = None,
+        agent_did: Optional[str] = None,
+    ) -> DelegationResult:
+        body: dict[str, Any] = {
+            "service": service,
+            "user_id": user_id,
+        }
+        if app_client_id:
+            body["appClientId"] = app_client_id
+        if scopes:
+            body["scopes"] = scopes
+        if agent_did:
+            body["agent_did"] = agent_did
+
+        data = self._request_json("POST", "/api/v1/delegate", body)
+        return self._build_delegation_result(data)
+
+    def list_connections(
+        self,
+        user_id: str,
+        app_client_id: Optional[str] = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, str] = {"user_id": user_id}
+        if app_client_id:
+            params["app_client_id"] = app_client_id
+
+        data = self._request_json("GET", f"/api/v1/connections?{urlencode(params)}")
+        return list(data.get("connections", []))
+
+    def get_user_connections(
+        self,
+        user_id: str,
+        app_client_id: Optional[str] = None,
+    ) -> list[Connection]:
+        return self._build_connections(
+            {"connections": self.list_connections(user_id, app_client_id)},
+        )
+
+    def revoke(
+        self,
+        service: str,
+        user_id: str,
+        app_client_id: Optional[str] = None,
+    ) -> None:
+        params: dict[str, str] = {"user_id": user_id}
+        if app_client_id:
+            params["app_client_id"] = app_client_id
+
+        self._request_no_content("DELETE", f"/api/v1/connections/{service}?{urlencode(params)}")
+
+    def revoke_agent(self, agent_id: str) -> None:
+        self._request_no_content("POST", f"/api/v1/agents/{agent_id}/revoke-all", {})
+
+    def _request_json(self, method: str, path: str, body: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+        response = self._client.request(method, path, json=body)
+        payload = self._handle_response(response)
+        if not isinstance(payload, dict):
+            raise CredError("Expected JSON object response", "invalid_response", response.status_code)
+        return payload
+
+    def _request_no_content(self, method: str, path: str, body: Optional[dict[str, Any]] = None) -> None:
+        response = self._client.request(method, path, json=body)
+        if response.status_code != 204:
+            self._handle_response(response)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "Cred":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncCred(_CredBase):
+    """Asynchronous client for the Cred credential delegation API."""
+
+    def __init__(
+        self,
+        agent_token: str,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> None:
+        super().__init__(agent_token=agent_token, base_url=base_url)
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=self._auth_headers(),
+            timeout=30.0,
+        )
+
+    async def delegate(
+        self,
+        service: str,
+        user_id: str,
+        app_client_id: Optional[str] = None,
+        scopes: Optional[list[str]] = None,
+        agent_did: Optional[str] = None,
+    ) -> DelegationResult:
+        body: dict[str, Any] = {
+            "service": service,
+            "user_id": user_id,
+        }
+        if app_client_id:
+            body["appClientId"] = app_client_id
+        if scopes:
+            body["scopes"] = scopes
+        if agent_did:
+            body["agent_did"] = agent_did
+
+        data = await self._request_json("POST", "/api/v1/delegate", body)
+        return self._build_delegation_result(data)
+
+    async def list_connections(
+        self,
+        user_id: str,
+        app_client_id: Optional[str] = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, str] = {"user_id": user_id}
+        if app_client_id:
+            params["app_client_id"] = app_client_id
+
+        data = await self._request_json("GET", f"/api/v1/connections?{urlencode(params)}")
+        return list(data.get("connections", []))
+
+    async def get_user_connections(
+        self,
+        user_id: str,
+        app_client_id: Optional[str] = None,
+    ) -> list[Connection]:
+        return self._build_connections(
+            {"connections": await self.list_connections(user_id, app_client_id)},
+        )
+
+    async def revoke(
+        self,
+        service: str,
+        user_id: str,
+        app_client_id: Optional[str] = None,
+    ) -> None:
+        params: dict[str, str] = {"user_id": user_id}
+        if app_client_id:
+            params["app_client_id"] = app_client_id
+
+        await self._request_no_content("DELETE", f"/api/v1/connections/{service}?{urlencode(params)}")
+
+    async def revoke_agent(self, agent_id: str) -> None:
+        await self._request_no_content("POST", f"/api/v1/agents/{agent_id}/revoke-all", {})
+
+    async def _request_json(self, method: str, path: str, body: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+        response = await self._client.request(method, path, json=body)
+        payload = self._handle_response(response)
+        if not isinstance(payload, dict):
+            raise CredError("Expected JSON object response", "invalid_response", response.status_code)
+        return payload
+
+    async def _request_no_content(self, method: str, path: str, body: Optional[dict[str, Any]] = None) -> None:
+        response = await self._client.request(method, path, json=body)
+        if response.status_code != 204:
+            self._handle_response(response)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncCred":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

cred_auth-1.0.0/cred/exceptions.py

@@ -0,0 +1,46 @@
+"""Cred SDK — Exception classes."""
+
+
+class CredError(Exception):
+    """Base exception for all Cred API errors."""
+
+    def __init__(self, message: str, code: str, status_code: int) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(message={str(self)!r}, code={self.code!r}, status_code={self.status_code})"
+
+
+class ConsentRequiredError(CredError):
+    """Raised when a user has not yet consented to a service.
+
+    The ``consent_url`` attribute contains the URL to redirect the user to
+    complete the OAuth consent flow.
+    """
+
+    def __init__(self, message: str, consent_url: str) -> None:
+        super().__init__(message, "consent_required", 403)
+        self.consent_url = consent_url
+
+
+class AgentRevokedException(CredError):
+    """Raised when the agent token has been revoked server-side."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, "agent_revoked", 403)
+
+
+class ScopeCeilingException(CredError):
+    """Raised when requested scopes exceed the agent's ceiling."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, "scope_ceiling_exceeded", 403)
+
+
+class RateLimitException(CredError):
+    """Raised when the API rate limits the request."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, "rate_limited", 429)