Metadata-Version: 2.5
Name: auth51
Version: 0.6.8
Summary: auth51 client (embed mode) — in-process egress interception that gives every agent action a scoped, verifiable, DPoP-bound intent token, minted at the source and verified at the resource.
Project-URL: Homepage, https://auth51.com
Project-URL: Repository, https://github.com/unforge-io/auth51-client-python
Author-email: unforge <dev-admin@unforge.io>
License: Proprietary
Keywords: agent-identity,ai-agents,auth51,dpop,intent-token,mcp,oauth
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: auth51-checksum>=0.4.0
Requires-Dist: cryptography>=42
Requires-Dist: pyjwt>=2.9
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# auth51 — Python client (embed mode)

The in-process enforcement point: it intercepts your agent's egress and gives
every governed call a **scoped, verifiable intent token** — minted at the source,
verified at the resource. This is the generalized, MCP-era successor to the
original A-JWT client shim, with **contextvar-based agent attribution** (no call-
stack introspection) per DESIGN §7b.

It's the **durable, unbypassable** path: it sees *all* egress in-process (native
tool calls *and* MCP calls), and depends only on the HTTP library — not on any
agent host's conventions.

## Use
```python
import auth51

auth51.configure(
    authority_url="https://authority.auth51.com",
    client_id="...", client_secret="...",
    audiences=["api.internal"],          # hosts to govern; everything else passes through
)

with auth51.agent("ReviewBot", checksum=agent_checksum, scope="read:repo"):
    httpx.get("https://api.internal/repos/...")   # ← stamped with an intent token
```
Config can also come from env: `AUTH51_AUTHORITY_URL`, `AUTH51_CLIENT_ID`,
`AUTH51_CLIENT_SECRET`, `AUTH51_AUDIENCES` (comma-sep), `AUTH51_FAIL_OPEN`.

## How it works

- **One import installs it** (idempotent; a no-op until configured + inside an `agent()` context).
- A framework adapter (LangChain/CrewAI — next) or the app sets the current agent via a contextvar at the tool-call boundary; the interceptor reads it.
- On governed egress: mint a scoped intent token (Hop A) → attach as a Bearer header → forward. Minting uses **stdlib urllib** so it never re-enters the patched HTTP client.
- **fail-open** by default (mint failure → forward unstamped, don't wedge the agent); set `fail_open=False` to fail closed.

## One application across multiple containers

Install `auth51` in every participating Python service, including the router
when you need to observe the router's own downstream calls. Associate their
credentials with the **same Authority application**, and set the same
`AUTH51_APP_ID` and Authority URL everywhere. A run's Authority execution ID is
propagated between services so the console collects their spans and governance
decisions under one execution. Each independent incoming request starts its own
run; sharing an app ID does not merge unrelated requests.

### Container configuration

Example for an agent service that calls a LiteLLM router and a worker:

```dotenv
AUTH51_APP_ID=my-application
AUTH51_SERVICE_NAME=agent
AUTH51_PROPAGATION_KEY=<random-secret-shared-by-this-apps-services>
AUTH51_PROPAGATION_ORIGINS=http://litellm:4000,http://worker:8000
AUTH51_LLM_ROUTER_HOSTS={"litellm":"auto","custom-router":"anthropic"}
```

Continue supplying the service's usual `AUTH51_CLIENT_ID` and
`AUTH51_CLIENT_SECRET`. Generate a propagation key with
`python -c "import secrets; print(secrets.token_urlsafe(32))"` and store it in
your secret manager. Use a different key for each application and environment.
Every service receives the same application settings and key, its own service
name, and an explicit list of the internal origins it calls. Origins include
scheme and port; no wildcard matching is performed. Use HTTPS outside a trusted
local container network.

The receiver must activate the same application's configuration before the
middleware runs. Multi-tenant hosts should select `auth51.using(...)` from their
authenticated tenant context first; never choose an app or key from the inbound
context itself. `using()` also accepts `service_name`, `propagation_key`,
`propagation_origins`, and `llm_router_hosts`.

### Receive and continue HTTP requests

Add the dependency-free ASGI middleware to FastAPI, Starlette, or another ASGI
service in **every participating container**:

```python
import auth51
from fastapi import FastAPI

app = FastAPI()
app.add_middleware(auth51.Auth51Middleware)
```

The existing HTTP interceptors add `x-auth51-context` automatically to calls
made through installed `httpx`, `httpx2`, or `requests`, only for allowed origins.
The middleware verifies the signature, application, Authority, and freshness,
then resumes the existing execution. It restores caller state when the request
finishes and isolates concurrent requests. With no incoming context, the request
starts isolated and the normal first-egress auto-run opens a new execution.
Invalid context returns HTTP 400 before invoking the handler.

The snapshot carries the execution mode, acting agent/checksum, delegation chain,
completed steps, previous token ID, and the built-in recorder's parent span. The
receiver's own model observation can derive its local agent identity. No OAuth
credentials, prompt text, or tools are transmitted in this header. Redirects to
unlisted origins have the header removed before transport. Span attributes include
`service.name` and `auth51.app_id` for inspecting the contributing services.

Context is valid for five minutes, with 30 seconds of clock-skew allowance, and
has a 16 KiB size limit. It is not a replacement for application authentication
or an authorization token. All participating services are in one trust domain;
Authority checks on downstream mints still apply. The signed envelope can be
replayed within its freshness window, so retain your normal request authentication
and idempotency controls.

### LLM routers

OpenRouter's `openrouter.ai` is recognized as OpenAI-shaped by default. For
LiteLLM and custom gateways, map the exact hostname to `openai` (Chat Completions
or Responses request shape), `anthropic` (Messages request shape), or `auto`
for a gateway serving both formats. This is
independent from `AUTH51_AUDIENCES`, which selects resource hosts to govern.
Merely recognizing a router does not add it to the propagation allowlist.

An external hosted router can be observed at the calling service without
receiving the internal context header. For an internal router's own downstream
spans to join the run, install the client and middleware in that router as well.
Non-Python services need an implementation of the context contract; installation
in adjacent Python containers cannot inspect another process's outbound calls.

### Queues and other server frameworks

Use the same envelope explicitly at the message or request boundary:

```python
# Producer, during an active Authority execution:
message = {"auth51_context": auth51.export_context(), "task": task}

# Consumer, after authenticating the message and selecting its app config:
with auth51.incoming_context(message.get("auth51_context")):
    handle_task(message["task"])
```

The context helpers do not open a new execution on export: the producer needs an
active Authority-issued run. For messages delayed beyond five minutes, establish
a fresh execution rather than replaying expired context. Context follows the call
direction; parallel branches share an execution but maintain their own local step
snapshots. This does not provide a global scheduler or merge branch state back
into the caller.

## Retained from the original A-JWT client shim
- **Startup-sync (`load_agents`)** — preload registered agents from the authority, index by checksum, detect collisions, and fail-fast on drift when the app declares expected checksums. *Boot-time validation: a mis-deployed agent is caught before it runs.*
- **Workflow seams** — `with auth51.workflow(id): ...` + `record_step(...)` track an execution; the chain + completed-steps + `prev_jti` ride into each intent token's `delegation_context` (§4.3 tamper-evident trace).
- **contextvar attribution** + smart caching — kept; **call-stack introspection dropped.**

## Status
- ✅ contextvar agent attribution · httpx **sync + async** + **requests** interception · mint + attach · fail-open/closed
- ✅ `load_agents()` startup-sync (cache + collision + drift validation) · workflow seams (delegation_context + `prev_jti` chain)
- ✅ LangChain adapter (`auth51.adapters.langchain.Auth51CallbackHandler`) — sets agent context + records steps at tool boundaries
- ⏭️ next: PoP signing (the `cnf` binding) · MCP `_meta` injection · `aiohttp` · local checksum recompute (shared lib) · live e2e against the deployed authority
