langchain-nuggets 1.0.0

Nuggets authority middleware for LangChain / LangGraph

langchain-nuggets

Authority middleware for LangChain / LangGraph — pre-execution trust enforcement on every tool call.

Wrap any ToolNode and the middleware calls the Nuggets authority endpoint before each tool executes. The backend evaluates a scoped delegation, returns an ALLOW or DENY decision, and signs an audit proof. Tools that aren't allowed never run.

Installation

pip install langchain-nuggets

For LangGraph Platform OIDC auth:

pip install langchain-nuggets[langgraph]

Authority Middleware

from langchain_nuggets.middleware import NuggetsAuthorityMiddleware, MiddlewareConfig
from langgraph.prebuilt import ToolNode

config = MiddlewareConfig(
    api_url="https://accounts.nuggets.life",
    oidc_issuer_url="https://auth.nuggets.life",
    agent_id="did:web:auth.nuggets.life:your-agent-id",
    controller_id="did:web:auth.nuggets.life:your-controller-id",
    delegation_id="42",
    agent_private_key="/secrets/agent-jwks.json",
)

middleware = NuggetsAuthorityMiddleware(config)

tool_node = ToolNode(
    tools=your_tools,
    wrap_tool_call=middleware.wrap_tool_call,
)

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; cryptographic proof artifact emitted
DENY	Tool blocked; structured error returned with reason_code
ERROR	Fail closed — tool not executed

To provision the agent identity, private key, and delegation referenced above, see the agent provisioning runbook.

Proof verification (on by default)

Every ALLOW carries a proof signed by the authority, and the SDK verifies it before the tool runs — discovering the authority's signing identity from {api_url}/.well-known/authority-configuration, pinning the proof's issuer to that authority, verifying the signature against the published JWKS, and binding the proof to the request. Any failure fails closed: DENY with reason_code = PROOF_VERIFICATION_FAILED, tool not run. On by default — no config.

Every decision is therefore independently verifiable. A third party can validate an emitted proof out-of-band:

from langchain_nuggets.middleware import verify_authority_proof, discover_authority

issuer, jwks_uri = discover_authority("https://accounts.nuggets.life")
verify_authority_proof(proof_jws, expected={...}, issuer=issuer, jwks_uri=jwks_uri)

Opt out only deliberately (e.g. an offline harness verifying proofs separately): MiddlewareConfig(..., verify_proofs=False).

With create_agent

For the LangChain create_agent API, install the agent extra and use the AgentMiddleware adapter (same config, same enforcement):

pip install langchain-nuggets[agent]

from langchain.agents import create_agent
from langchain_nuggets.middleware import NuggetsAuthorityAgentMiddleware, MiddlewareConfig

agent = create_agent(
    model="...",
    tools=your_tools,
    middleware=[NuggetsAuthorityAgentMiddleware(MiddlewareConfig(...))],
)

Agent private key

The accounts portal generates an RS256 keypair at agent creation and lets you download the private key as a JWKS file. MiddlewareConfig.agent_private_key accepts:

• A filesystem path to a PEM, JWK JSON, or JWKS JSON file
• A raw PEM string
• A JWK or JWKS dict

The key is never transmitted; only the signed agent_proof JWS is sent.

Test mode

test_mode=True short-circuits the live auth flow during local development — every check returns ALLOW, no HTTP is made, and the emitted proof artifact is flagged as test-mode-unverifiable.

LangGraph Platform OIDC auth

from langchain_nuggets.langgraph import NuggetsAuth

nuggets = NuggetsAuth(issuer_url="https://auth.nuggets.life")
auth = nuggets.auth  # pass to langgraph.json

Pre-built authorization helpers:

from langchain_nuggets.langgraph import require_scopes, ownership_filter

Self-hosted / private CA

Point the URLs at your own deployment and pass ca_cert to either constructor:

MiddlewareConfig(
    api_url="https://nuggets.internal.example.com",
    oidc_issuer_url="https://oidc.internal.example.com",
    # ...
    ca_cert="/etc/ssl/private-ca/nuggets-ca.pem",
)

Set verify_ssl=False to disable TLS verification (development only).

About Nuggets

Nuggets provides decentralized identity and verifiable trust infrastructure for people and AI agents. Learn more at nuggets.life.

License

MIT