cred-langchain 0.1.0__tar.gz

cred_langchain-0.1.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_langchain-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: cred-langchain
+Version: 0.1.0
+Summary: Cred LangChain integration — credential delegation tools for LangChain agents
+Author-email: Cred <hello@cred.ninja>
+License: Apache-2.0
+Keywords: ai-agents,cred,delegation,langchain,oauth
+Requires-Python: >=3.9
+Requires-Dist: cred-auth>=0.1.0
+Requires-Dist: langchain-core>=0.2
+Provides-Extra: dev
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cred-langchain
+
+LangChain integration for Cred. OAuth2 credential delegation for AI agents.
+
+## Install
+
+```bash
+pip install cred-langchain
+```
+
+## Quick Start
+
+```python
+import os
+from cred_langchain import CredToolkit
+from cred import ConsentRequiredError
+
+toolkit = CredToolkit(
+    agent_token=os.environ["CRED_AGENT_TOKEN"],
+    user_id="user_123",
+)
+tools = toolkit.get_tools()
+# tools = [CredDelegateTool, CredStatusTool, CredRevokeTool]
+
+# Use with any LangChain agent
+from langchain.agents import AgentExecutor
+agent = AgentExecutor(agent=..., tools=tools)
+```
+
+## Tools
+
+| Tool | Name | Description |
+|------|------|-------------|
+| `CredDelegateTool` | `cred_delegate` | Get an OAuth access token for a service |
+| `CredStatusTool` | `cred_status` | List user's connected services |
+| `CredRevokeTool` | `cred_revoke` | Revoke a service connection |
+
+## Handling Consent
+
+When a user hasn't connected a service yet, `CredDelegateTool` raises `ConsentRequiredError`.
+Catch it and redirect the user to `e.consent_url` to complete the OAuth flow.
+
+## Cred Cloud (Coming Soon)
+
+Managed cloud delegation is coming. [Join the waitlist](https://cred.ninja/waitlist).

cred_langchain-0.1.0/README.md

@@ -0,0 +1,45 @@
+# cred-langchain
+
+LangChain integration for Cred. OAuth2 credential delegation for AI agents.
+
+## Install
+
+```bash
+pip install cred-langchain
+```
+
+## Quick Start
+
+```python
+import os
+from cred_langchain import CredToolkit
+from cred import ConsentRequiredError
+
+toolkit = CredToolkit(
+    agent_token=os.environ["CRED_AGENT_TOKEN"],
+    user_id="user_123",
+)
+tools = toolkit.get_tools()
+# tools = [CredDelegateTool, CredStatusTool, CredRevokeTool]
+
+# Use with any LangChain agent
+from langchain.agents import AgentExecutor
+agent = AgentExecutor(agent=..., tools=tools)
+```
+
+## Tools
+
+| Tool | Name | Description |
+|------|------|-------------|
+| `CredDelegateTool` | `cred_delegate` | Get an OAuth access token for a service |
+| `CredStatusTool` | `cred_status` | List user's connected services |
+| `CredRevokeTool` | `cred_revoke` | Revoke a service connection |
+
+## Handling Consent
+
+When a user hasn't connected a service yet, `CredDelegateTool` raises `ConsentRequiredError`.
+Catch it and redirect the user to `e.consent_url` to complete the OAuth flow.
+
+## Cred Cloud (Coming Soon)
+
+Managed cloud delegation is coming. [Join the waitlist](https://cred.ninja/waitlist).

cred_langchain-0.1.0/cred_langchain/__init__.py

@@ -0,0 +1,32 @@
+"""Cred LangChain integration."""
+
+from pydantic import SecretStr
+
+from cred import Cred
+from .toolkit import CredToolkit
+from .tools import CredDelegateTool, CredStatusTool, CredRevokeTool
+
+
+def secret_from_cred(
+    service: str,
+    user_id: str,
+    cred: Cred,
+    scopes: list[str] | None = None,
+    app_client_id: str | None = None,
+) -> SecretStr:
+    """Drop-in replacement for secret_from_env() backed by Cred delegation."""
+    result = cred.delegate(
+        service=service,
+        user_id=user_id,
+        app_client_id=app_client_id,
+        scopes=scopes,
+    )
+    return SecretStr(result.access_token)
+
+__all__ = [
+    "CredToolkit",
+    "CredDelegateTool",
+    "CredStatusTool",
+    "CredRevokeTool",
+    "secret_from_cred",
+]

cred_langchain-0.1.0/cred_langchain/toolkit.py

@@ -0,0 +1,54 @@
+"""Cred LangChain Toolkit — bundles all Cred tools for use with LangChain agents."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from langchain_core.tools import BaseTool
+
+from cred import Cred
+from .tools import CredDelegateTool, CredStatusTool, CredRevokeTool
+
+
+class CredToolkit:
+    """LangChain toolkit that provides Cred credential delegation tools.
+
+    Instantiate once per agent invocation with the target user's ID.
+    All tools share the same Cred client and user context.
+
+    Example::
+
+        from cred_langchain import CredToolkit
+
+        toolkit = CredToolkit(
+            agent_token=os.environ["CRED_AGENT_TOKEN"],
+            user_id="user_123",
+        )
+        tools = toolkit.get_tools()
+        # Pass tools to your LangChain AgentExecutor
+    """
+
+    def __init__(
+        self,
+        agent_token: str,
+        user_id: str,
+        base_url: str = "https://api.cred.ninja",
+    ) -> None:
+        self._cred = Cred(agent_token=agent_token, base_url=base_url)
+        self._user_id = user_id
+
+    def get_tools(self) -> list[BaseTool]:
+        """Return all Cred tools pre-configured with this toolkit's user context."""
+        delegate = CredDelegateTool()
+        delegate._cred = self._cred
+        delegate._user_id = self._user_id
+
+        status = CredStatusTool()
+        status._cred = self._cred
+        status._user_id = self._user_id
+
+        revoke = CredRevokeTool()
+        revoke._cred = self._cred
+        revoke._user_id = self._user_id
+
+        return [delegate, status, revoke]

cred_langchain-0.1.0/cred_langchain/tools.py

@@ -0,0 +1,150 @@
+"""Cred LangChain Tools — individual BaseTool implementations."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import TYPE_CHECKING, Any, Optional, Type
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from cred import Cred
+
+
+# ── Input schemas ─────────────────────────────────────────────────────────────
+
+class DelegateInput(BaseModel):
+    service: str = Field(description="Service slug to get a token for (e.g. 'google', 'github')")
+    app_client_id: str = Field(description="The Cred app client ID to delegate for")
+    scopes: list[str] = Field(
+        default_factory=list,
+        description="OAuth scopes to request (e.g. ['calendar.readonly']). "
+                    "Leave empty to use all consented scopes.",
+    )
+
+
+class RevokeInput(BaseModel):
+    service: str = Field(description="Service slug to revoke (e.g. 'google', 'github')")
+    app_client_id: Optional[str] = Field(
+        default=None,
+        description="Optional app client ID to scope the revocation.",
+    )
+
+
+# ── Tools ─────────────────────────────────────────────────────────────────────
+
+class CredDelegateTool(BaseTool):
+    """Get an OAuth access token for a third-party service on behalf of the current user."""
+
+    name: str = "cred_delegate"
+    description: str = (
+        "Get an OAuth access token for a third-party service on behalf of the current user. "
+        "Returns the access token, expiry, service name, and granted scopes. "
+        "Raises ConsentRequiredError (with consent_url) if the user hasn't connected the service."
+    )
+    args_schema: Type[BaseModel] = DelegateInput
+
+    # Injected by CredToolkit
+    _cred: Any = None
+    _user_id: str = ""
+    _cache: dict[tuple[str, str, tuple[str, ...]], tuple[Any, float]] = {}
+
+    def _get_delegation_result(
+        self,
+        service: str,
+        app_client_id: str,
+        scopes: Optional[list[str]],
+    ) -> Any:
+        resolved_scopes = scopes or []
+        cache_key = (service, app_client_id, tuple(resolved_scopes))
+        cached = self._cache.get(cache_key)
+        now = time.monotonic()
+        if cached and cached[1] > now:
+            return cached[0]
+
+        result = self._cred.delegate(
+            service=service,
+            user_id=self._user_id,
+            app_client_id=app_client_id,
+            scopes=resolved_scopes,
+        )
+
+        expires_in = getattr(result, "expires_in", None)
+        refresh_deadline = 0.0
+        if isinstance(expires_in, int) and expires_in > 60:
+            refresh_deadline = now + expires_in - 60
+        self._cache[cache_key] = (result, refresh_deadline)
+        return result
+
+    def _run(
+        self,
+        service: str,
+        app_client_id: str,
+        scopes: Optional[list[str]] = None,
+        **kwargs: Any,
+    ) -> str:
+        result = self._get_delegation_result(service, app_client_id, scopes)
+        return json.dumps({
+            "access_token": result.access_token,
+            "token_type": result.token_type,
+            "expires_in": result.expires_in,
+            "service": result.service,
+            "scopes": result.scopes,
+            "delegation_id": result.delegation_id,
+        })
+
+
+class CredStatusTool(BaseTool):
+    """Check which third-party services the current user has connected."""
+
+    name: str = "cred_status"
+    description: str = (
+        "Check which third-party services the current user has connected via OAuth. "
+        "Returns a list of connected services with their granted scopes."
+    )
+
+    # Injected by CredToolkit
+    _cred: Any = None
+    _user_id: str = ""
+
+    def _run(self, **kwargs: Any) -> str:
+        connections = self._cred.get_user_connections(self._user_id)
+        return json.dumps([
+            {
+                "slug": c.slug,
+                "scopes_granted": c.scopes_granted,
+                "app_client_id": c.app_client_id,
+                "consented_at": c.consented_at,
+            }
+            for c in connections
+        ])
+
+
+class CredRevokeTool(BaseTool):
+    """Revoke the current user's connection to a third-party service."""
+
+    name: str = "cred_revoke"
+    description: str = (
+        "Revoke the current user's OAuth connection to a third-party service. "
+        "Use this when the user wants to disconnect a service."
+    )
+    args_schema: Type[BaseModel] = RevokeInput
+
+    # Injected by CredToolkit
+    _cred: Any = None
+    _user_id: str = ""
+
+    def _run(
+        self,
+        service: str,
+        app_client_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> str:
+        self._cred.revoke(
+            service=service,
+            user_id=self._user_id,
+            app_client_id=app_client_id,
+        )
+        return json.dumps({"revoked": True, "service": service})

cred_langchain-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cred-langchain"
+version = "0.1.0"
+description = "Cred LangChain integration — credential delegation tools for LangChain agents"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.9"
+authors = [{ name = "Cred", email = "hello@cred.ninja" }]
+keywords = ["cred", "langchain", "oauth", "delegation", "ai-agents"]
+dependencies = [
+    "cred-auth>=0.1.0",
+    "langchain-core>=0.2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "hatchling"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["cred_langchain"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cred_langchain-0.1.0/tests/test_toolkit.py

@@ -0,0 +1,280 @@
+"""Cred LangChain integration tests.
+
+Mocks the Cred client — no real HTTP, no real API calls.
+Tests focus on: tool wiring, input schema, output shape, error propagation.
+"""
+
+import json
+import warnings
+warnings.filterwarnings("ignore", category=UserWarning)
+
+from datetime import datetime, timezone
+from typing import Optional
+
+import pytest
+import httpx
+from unittest.mock import MagicMock, patch
+from langchain_core.tools import BaseTool
+from pydantic import SecretStr
+
+from cred import DelegationResult, Connection, ConsentRequiredError
+from cred_langchain import (
+    CredToolkit,
+    CredDelegateTool,
+    CredStatusTool,
+    CredRevokeTool,
+    secret_from_cred,
+)
+
+
+TOKEN = "cred_at_test"
+USER_ID = "user_123"
+
+
+def make_delegation_result(
+    *,
+    access_token: str = "at",
+    token_type: str = "Bearer",
+    expires_in: int = 3600,
+    service: str = "google",
+    scopes: Optional[list[str]] = None,
+    delegation_id: str = "del_1",
+) -> DelegationResult:
+    return DelegationResult(
+        access_token=access_token,
+        token_type=token_type,
+        expires_in=expires_in,
+        expires_at=datetime(2026, 3, 1, tzinfo=timezone.utc),
+        service=service,
+        scopes=scopes or [],
+        delegation_id=delegation_id,
+    )
+
+
+@pytest.fixture
+def mock_cred():
+    return MagicMock()
+
+
+@pytest.fixture
+def toolkit(mock_cred):
+    tk = CredToolkit(agent_token=TOKEN, user_id=USER_ID)
+    tk._cred = mock_cred
+    return tk
+
+
+# ── CredToolkit ───────────────────────────────────────────────────────────────
+
+class TestCredToolkit:
+    def test_get_tools_returns_three_tools(self, toolkit):
+        tools = toolkit.get_tools()
+        assert len(tools) == 3
+
+    def test_all_tools_are_base_tool_instances(self, toolkit):
+        tools = toolkit.get_tools()
+        assert all(isinstance(t, BaseTool) for t in tools)
+
+    def test_tool_names(self, toolkit):
+        names = {t.name for t in toolkit.get_tools()}
+        assert names == {"cred_delegate", "cred_status", "cred_revoke"}
+
+    def test_tools_share_user_id(self, toolkit):
+        tools = toolkit.get_tools()
+        for tool in tools:
+            assert tool._user_id == USER_ID
+
+    def test_tools_share_cred_client(self, toolkit, mock_cred):
+        tools = toolkit.get_tools()
+        for tool in tools:
+            assert tool._cred is mock_cred
+
+
+# ── CredDelegateTool ──────────────────────────────────────────────────────────
+
+class TestCredDelegateTool:
+    def test_returns_json_with_access_token(self, toolkit, mock_cred):
+        mock_cred.delegate.return_value = make_delegation_result(
+            access_token="ya29.mock",
+            expires_in=3600,
+            service="google",
+            scopes=["calendar.readonly"],
+            delegation_id="del_abc",
+        )
+
+        tools = toolkit.get_tools()
+        delegate = next(t for t in tools if t.name == "cred_delegate")
+        result = delegate._run(
+            service="google",
+            app_client_id="app_1",
+            scopes=["calendar.readonly"],
+        )
+
+        data = json.loads(result)
+        assert data["access_token"] == "ya29.mock"
+        assert data["service"] == "google"
+        assert data["expires_in"] == 3600
+        assert data["delegation_id"] == "del_abc"
+
+    def test_passes_user_id_to_cred(self, toolkit, mock_cred):
+        mock_cred.delegate.return_value = make_delegation_result()
+
+        tools = toolkit.get_tools()
+        delegate = next(t for t in tools if t.name == "cred_delegate")
+        delegate._run(service="google", app_client_id="app_1", scopes=[])
+
+        mock_cred.delegate.assert_called_once_with(
+            service="google",
+            user_id=USER_ID,
+            app_client_id="app_1",
+            scopes=[],
+        )
+
+    def test_propagates_consent_required_error(self, toolkit, mock_cred):
+        mock_cred.delegate.side_effect = ConsentRequiredError(
+            "User has not consented",
+            "https://api.cred.ninja/api/connect/google/authorize?app_client_id=app_1",
+        )
+
+        tools = toolkit.get_tools()
+        delegate = next(t for t in tools if t.name == "cred_delegate")
+
+        with pytest.raises(ConsentRequiredError) as exc_info:
+            delegate._run(service="google", app_client_id="app_1", scopes=["calendar.readonly"])
+
+        assert "/api/connect/google/authorize" in exc_info.value.consent_url
+
+    def test_has_args_schema(self, toolkit):
+        tools = toolkit.get_tools()
+        delegate = next(t for t in tools if t.name == "cred_delegate")
+        schema = delegate.args_schema.model_json_schema()
+        assert "service" in schema["properties"]
+        assert "scopes" in schema["properties"]
+
+    def test_real_cred_client_delegates_against_mock_server(self):
+        toolkit = CredToolkit(
+            agent_token=TOKEN,
+            user_id=USER_ID,
+            base_url="https://cred.example.com",
+        )
+        delegate = next(t for t in toolkit.get_tools() if t.name == "cred_delegate")
+
+        with patch("httpx.Client.request", return_value=httpx.Response(
+            200,
+            json={
+                "access_token": "ya29.real",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+                "service": "google",
+                "scopes": ["calendar.readonly"],
+                "delegation_id": "del_real",
+            },
+        )) as request_mock:
+            result = delegate._run(
+                service="google",
+                app_client_id="app_1",
+                scopes=["calendar.readonly"],
+            )
+
+        payload = json.loads(result)
+        assert payload["access_token"] == "ya29.real"
+        assert request_mock.called
+
+
+# ── CredStatusTool ────────────────────────────────────────────────────────────
+
+class TestCredStatusTool:
+    def test_returns_json_list_of_connections(self, toolkit, mock_cred):
+        mock_cred.get_user_connections.return_value = [
+            Connection(slug="google", scopes_granted=["calendar.readonly"],
+                       app_client_id="app1", consented_at="2026-03-01T00:00:00Z"),
+            Connection(slug="github", scopes_granted=["repo"],
+                       app_client_id="app1", consented_at="2026-03-01T00:00:00Z"),
+        ]
+
+        tools = toolkit.get_tools()
+        status = next(t for t in tools if t.name == "cred_status")
+        result = status._run()
+
+        data = json.loads(result)
+        assert len(data) == 2
+        assert data[0]["slug"] == "google"
+        assert data[1]["slug"] == "github"
+
+    def test_passes_user_id_to_cred(self, toolkit, mock_cred):
+        mock_cred.get_user_connections.return_value = []
+
+        tools = toolkit.get_tools()
+        status = next(t for t in tools if t.name == "cred_status")
+        status._run()
+
+        mock_cred.get_user_connections.assert_called_once_with(USER_ID)
+
+    def test_returns_empty_list_when_no_connections(self, toolkit, mock_cred):
+        mock_cred.get_user_connections.return_value = []
+        tools = toolkit.get_tools()
+        status = next(t for t in tools if t.name == "cred_status")
+        result = status._run()
+        assert json.loads(result) == []
+
+
+# ── CredRevokeTool ────────────────────────────────────────────────────────────
+
+class TestCredRevokeTool:
+    def test_returns_json_revoked_true(self, toolkit, mock_cred):
+        mock_cred.revoke.return_value = None
+
+        tools = toolkit.get_tools()
+        revoke = next(t for t in tools if t.name == "cred_revoke")
+        result = revoke._run(service="google")
+
+        data = json.loads(result)
+        assert data["revoked"] is True
+        assert data["service"] == "google"
+
+    def test_passes_user_id_and_service_to_cred(self, toolkit, mock_cred):
+        mock_cred.revoke.return_value = None
+
+        tools = toolkit.get_tools()
+        revoke = next(t for t in tools if t.name == "cred_revoke")
+        revoke._run(service="google", app_client_id="app1")
+
+        mock_cred.revoke.assert_called_once_with(
+            service="google",
+            user_id=USER_ID,
+            app_client_id="app1",
+        )
+
+    def test_has_args_schema(self, toolkit):
+        tools = toolkit.get_tools()
+        revoke = next(t for t in tools if t.name == "cred_revoke")
+        schema = revoke.args_schema.model_json_schema()
+        assert "service" in schema["properties"]
+
+
+class TestSecretFromCred:
+    def test_returns_secret_str_from_real_cred_client(self):
+        from cred import Cred
+
+        cred = Cred(agent_token=TOKEN, base_url="https://cred.example.com")
+
+        with patch("httpx.Client.request", return_value=httpx.Response(
+            200,
+            json={
+                "access_token": "ya29.secret",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+                "service": "google",
+                "scopes": ["calendar.readonly"],
+                "delegation_id": "del_secret",
+            },
+        )):
+            secret = secret_from_cred(
+                "google",
+                USER_ID,
+                cred,
+                scopes=["calendar.readonly"],
+                app_client_id="app_1",
+            )
+
+        assert isinstance(secret, SecretStr)
+        assert secret.get_secret_value() == "ya29.secret"