langchain-nuggets 0.1.0__tar.gz

langchain_nuggets-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+node_modules/
+dist/
+.turbo/
+*.tsbuildinfo
+.env
+.env.local
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/

langchain_nuggets-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: langchain-nuggets
+Version: 0.1.0
+Summary: Nuggets identity verification toolkit for LangChain Python
+Project-URL: Repository, https://github.com/NuggetsLtd/langchain-nuggets
+License-Expression: MIT
+Keywords: ai,identity,kyc,langchain,nuggets,tools,verification
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: langgraph-sdk>=0.1.0; extra == 'dev'
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pyjwt[crypto]>=2.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langgraph-sdk>=0.1.0; extra == 'langgraph'
+Requires-Dist: pyjwt[crypto]>=2.8.0; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# langchain-nuggets
+
+Nuggets identity verification toolkit for LangChain Python. Provides 11 ready-to-use tools for KYC, KYA, and credential verification that plug directly into any LangChain agent.
+
+## Installation
+
+```bash
+pip install langchain-nuggets
+```
+
+## Quick Start
+
+```python
+from langchain_nuggets import NuggetsToolkit
+
+# Config via env vars: NUGGETS_API_URL, NUGGETS_PARTNER_ID, NUGGETS_PARTNER_SECRET
+toolkit = NuggetsToolkit()
+tools = toolkit.get_tools()
+
+# Or pass config directly
+toolkit = NuggetsToolkit(
+    api_url="https://api.nuggets.life",
+    partner_id="your-partner-id",
+    partner_secret="your-secret",
+)
+```
+
+## Tools
+
+### KYC (Know Your Customer)
+
+| Tool | Description |
+|------|-------------|
+| `initiate_kyc_verification` | Start identity verification flow, returns deeplink/QR for Nuggets app |
+| `check_kyc_status` | Poll verification session status (pending/completed/failed/expired) |
+| `verify_age` | Selective disclosure age proof without revealing date of birth |
+| `verify_credential` | Request specific credential (address, email, phone, nationality) |
+
+### KYA (Know Your Agent)
+
+| Tool | Description |
+|------|-------------|
+| `register_agent_identity` | Register AI agent identity with DID and provenance signals |
+| `verify_agent_identity` | Verify another agent's identity and provenance |
+| `get_agent_trust_score` | Get trust score (0-1) based on verified signals |
+
+### Auth & Credentials
+
+| Tool | Description |
+|------|-------------|
+| `request_credential_presentation` | Ask user to present verifiable credentials |
+| `verify_presentation` | Check presentation status and verify credentials |
+| `initiate_oauth_flow` | Start OAuth 2.0/OIDC flow with Nuggets as IdP |
+| `check_auth_status` | Check user's authentication and verification status |
+
+## Usage with LangChain Agent
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain.agents import AgentExecutor, create_openai_tools_agent
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_nuggets import NuggetsToolkit
+
+toolkit = NuggetsToolkit()
+tools = toolkit.get_tools()
+
+llm = ChatOpenAI(model="gpt-4o", temperature=0)
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a helpful assistant that can verify user identities using Nuggets."),
+    ("human", "{input}"),
+    ("placeholder", "{agent_scratchpad}"),
+])
+
+agent = create_openai_tools_agent(llm, tools, prompt)
+executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
+
+result = executor.invoke({"input": "Verify alice@example.com"})
+```
+
+## Configuration
+
+| Parameter | Env Variable | Description |
+|-----------|-------------|-------------|
+| `api_url` | `NUGGETS_API_URL` | Nuggets API base URL |
+| `partner_id` | `NUGGETS_PARTNER_ID` | Your partner ID |
+| `partner_secret` | `NUGGETS_PARTNER_SECRET` | Your partner secret |
+
+
+## Self-Hosted Deployment
+
+All classes accept configurable URLs — point to your own Nuggets instance:
+
+```python
+toolkit = NuggetsToolkit(
+    api_url="https://nuggets.internal.example.com/api",
+    partner_id="your-partner-id",
+    partner_secret="your-secret",
+)
+```
+
+### Custom CA Certificates
+
+For self-hosted instances using a private CA:
+
+```python
+toolkit = NuggetsToolkit(
+    api_url="https://nuggets.internal.example.com/api",
+    partner_id="your-partner-id",
+    partner_secret="your-secret",
+    ca_cert="/etc/ssl/private-ca/nuggets-ca.pem",
+)
+```
+
+The `ca_cert` and `verify_ssl` parameters are also available on:
+- `NuggetsAuth(issuer_url=..., ca_cert=..., verify_ssl=...)`
+- `MiddlewareConfig(api_url=..., ca_cert=..., verify_ssl=...)`
+- `NuggetsApiClient({"api_url": ..., "ca_cert": ..., "verify_ssl": ...})`
+
+To disable TLS verification entirely (development/staging only):
+
+```python
+toolkit = NuggetsToolkit(..., verify_ssl=False)
+```
+
+## License
+
+MIT
+
+## Authority Middleware
+
+Intercept every LangChain/LangGraph tool call with pre-execution trust enforcement. The middleware validates authority against the Nuggets control plane, blocks unauthorized actions, and emits cryptographic proof artifacts.
+
+```python
+from langchain_nuggets.middleware import NuggetsAuthorityMiddleware, MiddlewareConfig
+from langgraph.prebuilt import ToolNode
+
+config = MiddlewareConfig(
+    api_url="https://api.nuggets.life",
+    partner_id="your-partner-id",
+    partner_secret="your-secret",
+    agent_id="agent-001",
+    controller_id="org-001",
+    delegation_id="del-001",
+)
+
+middleware = NuggetsAuthorityMiddleware(config)
+
+tool_node = ToolNode(
+    tools=your_tools,
+    wrap_tool_call=middleware.wrap_tool_call,   # sync
+    # awrap_tool_call=middleware.awrap_tool_call,  # async
+)
+```
+
+**Execution model:** `Agent → Tool Call → Nuggets Authority Check → Allow/Deny → Emit Proof`
+
+**Trust primitives enforced:** Actor Identity, Authority (delegation), Policy, Intent, Consent, Accountability (provenance).
+
+| Behaviour | Detail |
+|-----------|--------|
+| **ALLOW** | Tool executes, proof artifact emitted |
+| **DENY** | Tool blocked, structured error returned |
+| **ERROR** | Fail closed — tool not executed |
+
+Access proof artifacts after execution:
+
+```python
+for proof in middleware.proofs:
+    print(f"{proof.proof_id}: {proof.tool} latency={proof.latency_ms:.0f}ms")
+```
+
+See the [demo script](../../examples/python/authority_middleware_demo.py) for a complete working example.

langchain_nuggets-0.1.0/README.md

@@ -0,0 +1,172 @@
+# langchain-nuggets
+
+Nuggets identity verification toolkit for LangChain Python. Provides 11 ready-to-use tools for KYC, KYA, and credential verification that plug directly into any LangChain agent.
+
+## Installation
+
+```bash
+pip install langchain-nuggets
+```
+
+## Quick Start
+
+```python
+from langchain_nuggets import NuggetsToolkit
+
+# Config via env vars: NUGGETS_API_URL, NUGGETS_PARTNER_ID, NUGGETS_PARTNER_SECRET
+toolkit = NuggetsToolkit()
+tools = toolkit.get_tools()
+
+# Or pass config directly
+toolkit = NuggetsToolkit(
+    api_url="https://api.nuggets.life",
+    partner_id="your-partner-id",
+    partner_secret="your-secret",
+)
+```
+
+## Tools
+
+### KYC (Know Your Customer)
+
+| Tool | Description |
+|------|-------------|
+| `initiate_kyc_verification` | Start identity verification flow, returns deeplink/QR for Nuggets app |
+| `check_kyc_status` | Poll verification session status (pending/completed/failed/expired) |
+| `verify_age` | Selective disclosure age proof without revealing date of birth |
+| `verify_credential` | Request specific credential (address, email, phone, nationality) |
+
+### KYA (Know Your Agent)
+
+| Tool | Description |
+|------|-------------|
+| `register_agent_identity` | Register AI agent identity with DID and provenance signals |
+| `verify_agent_identity` | Verify another agent's identity and provenance |
+| `get_agent_trust_score` | Get trust score (0-1) based on verified signals |
+
+### Auth & Credentials
+
+| Tool | Description |
+|------|-------------|
+| `request_credential_presentation` | Ask user to present verifiable credentials |
+| `verify_presentation` | Check presentation status and verify credentials |
+| `initiate_oauth_flow` | Start OAuth 2.0/OIDC flow with Nuggets as IdP |
+| `check_auth_status` | Check user's authentication and verification status |
+
+## Usage with LangChain Agent
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain.agents import AgentExecutor, create_openai_tools_agent
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_nuggets import NuggetsToolkit
+
+toolkit = NuggetsToolkit()
+tools = toolkit.get_tools()
+
+llm = ChatOpenAI(model="gpt-4o", temperature=0)
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a helpful assistant that can verify user identities using Nuggets."),
+    ("human", "{input}"),
+    ("placeholder", "{agent_scratchpad}"),
+])
+
+agent = create_openai_tools_agent(llm, tools, prompt)
+executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
+
+result = executor.invoke({"input": "Verify alice@example.com"})
+```
+
+## Configuration
+
+| Parameter | Env Variable | Description |
+|-----------|-------------|-------------|
+| `api_url` | `NUGGETS_API_URL` | Nuggets API base URL |
+| `partner_id` | `NUGGETS_PARTNER_ID` | Your partner ID |
+| `partner_secret` | `NUGGETS_PARTNER_SECRET` | Your partner secret |
+
+
+## Self-Hosted Deployment
+
+All classes accept configurable URLs — point to your own Nuggets instance:
+
+```python
+toolkit = NuggetsToolkit(
+    api_url="https://nuggets.internal.example.com/api",
+    partner_id="your-partner-id",
+    partner_secret="your-secret",
+)
+```
+
+### Custom CA Certificates
+
+For self-hosted instances using a private CA:
+
+```python
+toolkit = NuggetsToolkit(
+    api_url="https://nuggets.internal.example.com/api",
+    partner_id="your-partner-id",
+    partner_secret="your-secret",
+    ca_cert="/etc/ssl/private-ca/nuggets-ca.pem",
+)
+```
+
+The `ca_cert` and `verify_ssl` parameters are also available on:
+- `NuggetsAuth(issuer_url=..., ca_cert=..., verify_ssl=...)`
+- `MiddlewareConfig(api_url=..., ca_cert=..., verify_ssl=...)`
+- `NuggetsApiClient({"api_url": ..., "ca_cert": ..., "verify_ssl": ...})`
+
+To disable TLS verification entirely (development/staging only):
+
+```python
+toolkit = NuggetsToolkit(..., verify_ssl=False)
+```
+
+## License
+
+MIT
+
+## Authority Middleware
+
+Intercept every LangChain/LangGraph tool call with pre-execution trust enforcement. The middleware validates authority against the Nuggets control plane, blocks unauthorized actions, and emits cryptographic proof artifacts.
+
+```python
+from langchain_nuggets.middleware import NuggetsAuthorityMiddleware, MiddlewareConfig
+from langgraph.prebuilt import ToolNode
+
+config = MiddlewareConfig(
+    api_url="https://api.nuggets.life",
+    partner_id="your-partner-id",
+    partner_secret="your-secret",
+    agent_id="agent-001",
+    controller_id="org-001",
+    delegation_id="del-001",
+)
+
+middleware = NuggetsAuthorityMiddleware(config)
+
+tool_node = ToolNode(
+    tools=your_tools,
+    wrap_tool_call=middleware.wrap_tool_call,   # sync
+    # awrap_tool_call=middleware.awrap_tool_call,  # async
+)
+```
+
+**Execution model:** `Agent → Tool Call → Nuggets Authority Check → Allow/Deny → Emit Proof`
+
+**Trust primitives enforced:** Actor Identity, Authority (delegation), Policy, Intent, Consent, Accountability (provenance).
+
+| Behaviour | Detail |
+|-----------|--------|
+| **ALLOW** | Tool executes, proof artifact emitted |
+| **DENY** | Tool blocked, structured error returned |
+| **ERROR** | Fail closed — tool not executed |
+
+Access proof artifacts after execution:
+
+```python
+for proof in middleware.proofs:
+    print(f"{proof.proof_id}: {proof.tool} latency={proof.latency_ms:.0f}ms")
+```
+
+See the [demo script](../../examples/python/authority_middleware_demo.py) for a complete working example.

langchain_nuggets-0.1.0/langchain_nuggets/__init__.py

@@ -0,0 +1,77 @@
+"""Nuggets identity verification toolkit for LangChain."""
+from langchain_nuggets.client.nuggets_api_client import (
+    NuggetsApiClient,
+    NuggetsApiClientError,
+)
+from langchain_nuggets.toolkit import NuggetsToolkit
+
+# Auth tools
+from langchain_nuggets.tools.auth import (
+    CheckAuthStatus,
+    InitiateOAuthFlow,
+    RequestCredentialPresentation,
+    VerifyPresentation,
+)
+from langchain_nuggets.tools.base import NuggetsBaseTool
+
+# KYA tools
+from langchain_nuggets.tools.kya import (
+    GetAgentTrustScore,
+    RegisterAgentIdentity,
+    VerifyAgentIdentity,
+)
+
+# KYC tools
+from langchain_nuggets.tools.kyc import (
+    CheckKycStatus,
+    InitiateKycVerification,
+    VerifyAge,
+    VerifyCredential,
+)
+
+# LangGraph auth (optional — requires langgraph-sdk)
+try:
+    from langchain_nuggets.langgraph import NuggetsAuth, NuggetsAuthError
+except ImportError:
+    pass
+
+# Authority Middleware (optional — requires langchain-core)
+try:
+    from langchain_nuggets.middleware import (
+        MiddlewareConfig,
+        NuggetsAuthorityMiddleware,
+        ProofArtifact,
+    )
+except ImportError:
+    pass
+
+__all__ = [
+    # Toolkit
+    "NuggetsToolkit",
+    # Client
+    "NuggetsApiClient",
+    "NuggetsApiClientError",
+    # Base
+    "NuggetsBaseTool",
+    # KYC
+    "InitiateKycVerification",
+    "CheckKycStatus",
+    "VerifyAge",
+    "VerifyCredential",
+    # KYA
+    "RegisterAgentIdentity",
+    "VerifyAgentIdentity",
+    "GetAgentTrustScore",
+    # Auth
+    "RequestCredentialPresentation",
+    "VerifyPresentation",
+    "InitiateOAuthFlow",
+    "CheckAuthStatus",
+    # LangGraph (optional)
+    "NuggetsAuth",
+    "NuggetsAuthError",
+    # Middleware (optional)
+    "NuggetsAuthorityMiddleware",
+    "MiddlewareConfig",
+    "ProofArtifact",
+]

langchain_nuggets-0.1.0/langchain_nuggets/client/__init__.py

@@ -0,0 +1,3 @@
+from langchain_nuggets.client.nuggets_api_client import NuggetsApiClient, NuggetsApiClientError
+
+__all__ = ["NuggetsApiClient", "NuggetsApiClientError"]

langchain_nuggets-0.1.0/langchain_nuggets/client/nuggets_api_client.py

@@ -0,0 +1,192 @@
+"""Nuggets API client with automatic authentication and token caching."""
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Dict, Optional, Union
+
+import httpx
+
+
+class NuggetsApiClientError(Exception):
+    """Error from the Nuggets API."""
+
+    def __init__(self, message: str, code: str, status_code: int) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+
+
+class NuggetsApiClient:
+    """HTTP client for the Nuggets API with automatic auth token management."""
+
+    def __init__(self, config: Dict[str, Any]) -> None:
+        self._api_url: str = config["api_url"]
+        self._partner_id: str = config["partner_id"]
+        self._partner_secret: str = config["partner_secret"]
+        self._token: Optional[Dict[str, Any]] = None
+        self._sync_client: Optional[httpx.Client] = None
+        self._async_client: Optional[httpx.AsyncClient] = None
+
+        # TLS configuration for self-hosted deployments
+        verify_ssl: bool = config.get("verify_ssl", True)
+        ca_cert: Optional[str] = config.get("ca_cert")
+        if not verify_ssl:
+            self._verify: Union[bool, str] = False
+        elif ca_cert is not None:
+            self._verify = ca_cert
+        else:
+            self._verify = True
+
+    def _get_sync_client(self) -> httpx.Client:
+        if self._sync_client is None:
+            self._sync_client = httpx.Client(verify=self._verify)
+        return self._sync_client
+
+    def close(self) -> None:
+        """Close the sync HTTP client and release resources."""
+        if self._sync_client is not None:
+            self._sync_client.close()
+            self._sync_client = None
+
+    async def aclose(self) -> None:
+        """Close the async HTTP client and release resources."""
+        if self._async_client is not None:
+            await self._async_client.aclose()
+            self._async_client = None
+
+    def __enter__(self) -> "NuggetsApiClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    async def __aenter__(self) -> "NuggetsApiClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()
+
+    def _authenticate_sync(self) -> str:
+        if self._token and self._token["expires_at"] > time.time():
+            return self._token["access_token"]
+        client = self._get_sync_client()
+        response = client.post(
+            f"{self._api_url}/partner/auth",
+            json={"partnerId": self._partner_id, "partnerSecret": self._partner_secret},
+        )
+        if response.status_code >= 400:
+            raise NuggetsApiClientError(
+                "Authentication failed", "AUTH_FAILED", response.status_code
+            )
+        data = response.json()
+        self._token = {
+            "access_token": data["token"],
+            "expires_at": time.time() + data["expiresIn"],
+        }
+        return self._token["access_token"]
+
+    def _request_sync(self, method: str, path: str, body: Any = None) -> Any:
+        token = self._authenticate_sync()
+        client = self._get_sync_client()
+        kwargs: Dict[str, Any] = {
+            "method": method,
+            "url": f"{self._api_url}{path}",
+            "headers": {
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {token}",
+            },
+        }
+        if body is not None:
+            kwargs["content"] = json.dumps(body)
+        response = client.request(**kwargs)
+        try:
+            data = response.json()
+        except Exception:
+            if response.status_code >= 400:
+                raise NuggetsApiClientError(
+                    f"Request failed with status {response.status_code}",
+                    "UNKNOWN",
+                    response.status_code,
+                )
+            raise NuggetsApiClientError(
+                "Invalid JSON response", "PARSE_ERROR", response.status_code
+            )
+        if response.status_code >= 400:
+            raise NuggetsApiClientError(
+                data.get("message", "Request failed"),
+                data.get("code", "UNKNOWN"),
+                response.status_code,
+            )
+        return data
+
+    def get(self, path: str) -> Any:
+        return self._request_sync("GET", path)
+
+    def post(self, path: str, body: Any = None) -> Any:
+        return self._request_sync("POST", path, body)
+
+    # --- Async methods ---
+    async def _get_async_client(self) -> httpx.AsyncClient:
+        if self._async_client is None:
+            self._async_client = httpx.AsyncClient(verify=self._verify)
+        return self._async_client
+
+    async def _authenticate_async(self) -> str:
+        if self._token and self._token["expires_at"] > time.time():
+            return self._token["access_token"]
+        client = await self._get_async_client()
+        response = await client.post(
+            f"{self._api_url}/partner/auth",
+            json={"partnerId": self._partner_id, "partnerSecret": self._partner_secret},
+        )
+        if response.status_code >= 400:
+            raise NuggetsApiClientError(
+                "Authentication failed", "AUTH_FAILED", response.status_code
+            )
+        data = response.json()
+        self._token = {
+            "access_token": data["token"],
+            "expires_at": time.time() + data["expiresIn"],
+        }
+        return self._token["access_token"]
+
+    async def _request_async(self, method: str, path: str, body: Any = None) -> Any:
+        token = await self._authenticate_async()
+        client = await self._get_async_client()
+        kwargs: Dict[str, Any] = {
+            "method": method,
+            "url": f"{self._api_url}{path}",
+            "headers": {
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {token}",
+            },
+        }
+        if body is not None:
+            kwargs["content"] = json.dumps(body)
+        response = await client.request(**kwargs)
+        try:
+            data = response.json()
+        except Exception:
+            if response.status_code >= 400:
+                raise NuggetsApiClientError(
+                    f"Request failed with status {response.status_code}",
+                    "UNKNOWN",
+                    response.status_code,
+                )
+            raise NuggetsApiClientError(
+                "Invalid JSON response", "PARSE_ERROR", response.status_code
+            )
+        if response.status_code >= 400:
+            raise NuggetsApiClientError(
+                data.get("message", "Request failed"),
+                data.get("code", "UNKNOWN"),
+                response.status_code,
+            )
+        return data
+
+    async def aget(self, path: str) -> Any:
+        return await self._request_async("GET", path)
+
+    async def apost(self, path: str, body: Any = None) -> Any:
+        return await self._request_async("POST", path, body)

langchain_nuggets-0.1.0/langchain_nuggets/langgraph/__init__.py

@@ -0,0 +1,25 @@
+"""LangGraph auth integration with Nuggets identity provider.
+
+Requires the ``langgraph`` extra::
+
+    pip install langchain-nuggets[langgraph]
+"""
+from langchain_nuggets.langgraph.auth import NuggetsAuth
+from langchain_nuggets.langgraph.authorization import (
+    ownership_filter,
+    require_kyc,
+    require_scopes,
+)
+from langchain_nuggets.langgraph.token_verifier import NuggetsAuthError, NuggetsTokenVerifier
+from langchain_nuggets.langgraph.types import NuggetsAuthConfig, NuggetsUserInfo
+
+__all__ = [
+    "NuggetsAuth",
+    "NuggetsAuthConfig",
+    "NuggetsAuthError",
+    "NuggetsTokenVerifier",
+    "NuggetsUserInfo",
+    "ownership_filter",
+    "require_kyc",
+    "require_scopes",
+]