ubag (Python)

UBAG Web Layer — agent identity and routing at the web edge. FastAPI / Starlette middleware.

When an autonomous agent visits a website, UBAG verifies who it is and routes accordingly: humans to your normal site, credentialed agents to clean JSON-LD, unknown automation to a cryptographic challenge. Identity verification and site authorization are separate. Asymmetric by design — agent identity is an Ed25519 keypair; credentials are ES256 JWTs verifiable via JWKS, no shared secrets.

Early but real, pre-1.0, unaudited. See the full README and SECURITY.md.

Install

pip install "ubag[fastapi]"

Quick start

from fastapi import FastAPI
from ubag import UBAGMiddleware, generate_issuer_keypair

issuer_private, _ = generate_issuer_keypair()   # EC P-256 (ES256)
trusted_agents = {"ubag:replace-with-an-approved-agent-id"}

app = FastAPI()
app.add_middleware(
    UBAGMiddleware,
    origin="https://yoursite.com",
    issuer_key=issuer_private,                  # mints + verifies credentials
    server_secret="a-separate-random-32+char-secret",
    authorize_agent=lambda identity, request: identity["agent_id"] in trusted_agents,
    # site_meta is OPTIONAL — Branch B auto-extracts structured data from your
    # origin's HTML (JSON-LD/OpenGraph/meta). Pass site_meta only to override.
)

Your site now serves credentialed agents auto-extracted JSON-LD plus a labeled Markdown content layer (no hand-written metadata), proxies humans to your origin, challenges unknown automation, exposes /.well-known/ubag.json for discovery, and serves its issuer key as JWKS at /.well-known/jwks.json. Credentials are holder-of-key: agents attach a one-time request-bound proof-of-possession via agent.headers(method, absolute_url).

Teach your coding agent

ubag init            # you are serving a site through UBAG
ubag init --agent    # you are building an agent that reads UBAG-enabled sites
ubag init --both

Writes .agents/skills/ubag-*/SKILL.md into your project, and creates AGENTS.md and CLAUDE.md only if they do not already exist. An AGENTS.md you already have is never modified; the line to add is printed instead. Safe to re-run.

ubag init --check reports whether the copy in your repo is older than the installed SDK.

A Node/Express SDK with an identical, cross-verifiable wire format is in the same repo. Full docs, a runnable demo, and the protocol details: https://github.com/mohameduk/Ubag_protocol

MIT licensed.