ubag 0.2.0__py3-none-any.whl

ubag/__init__.py

@@ -0,0 +1,47 @@
+"""
+UBAG Protocol — Agent identity and routing middleware.
+
+The missing identity layer for MCP agents.
+"""
+from ubag._routing import RoutingBranch, resolve_branch
+from ubag._credential import issue_credential, validate_credential, CREDENTIAL_HEADER
+from ubag._challenge import generate_challenge, verify_challenge
+from ubag._agents_json import build_agents_json
+from ubag._keys import (
+    generate_agent_keypair,
+    generate_issuer_keypair,
+    issuer_public_from_private,
+    agent_id,
+    agent_sign,
+    agent_verify,
+    build_jwks,
+)
+from ubag.agent import AgentCredential
+
+__version__ = "0.2.0"
+__all__ = [
+    "UBAGMiddleware",
+    "AgentCredential",
+    "RoutingBranch",
+    "resolve_branch",
+    "issue_credential",
+    "validate_credential",
+    "generate_challenge",
+    "verify_challenge",
+    "build_agents_json",
+    "CREDENTIAL_HEADER",
+    "generate_agent_keypair",
+    "generate_issuer_keypair",
+    "issuer_public_from_private",
+    "agent_id",
+    "agent_sign",
+    "agent_verify",
+    "build_jwks",
+]
+
+# Lazy import so FastAPI/Starlette is optional
+def __getattr__(name: str):
+    if name == "UBAGMiddleware":
+        from ubag.middleware.fastapi import UBAGMiddleware
+        return UBAGMiddleware
+    raise AttributeError(f"module 'ubag' has no attribute {name!r}")

ubag/_agents_json.py

@@ -0,0 +1,60 @@
+"""
+ubag.json — machine-readable agent discovery file.
+
+Served automatically at /.well-known/ubag.json on every UBAG-enabled site
+(with /agents.json kept as a legacy alias). Tells MCP agents how to authenticate
+and what they can access. Deliberately *not* named agents.json — that filename is
+already used by unrelated specs (Wildcard, ARD, etc.); ubag.json avoids the clash.
+"""
+from __future__ import annotations
+
+
+def build_agents_json(
+    host: str,
+    credential_endpoint: str = "",
+    contact: str = "",
+    custom_fields: dict | None = None,
+) -> dict:
+    """
+    Build the ubag.json discovery document for a given host.
+
+    MCP agents should fetch this before making requests to understand
+    what credentials are required and what data is available.
+
+    `credential_endpoint` is where an agent obtains a credential. A self-issuing
+    site (one configured with an issuer key) mints credentials at its own
+    `/ubag/verify`, so when no endpoint is given we advertise that — no hosted
+    central registry is required.
+    """
+    credential_endpoint = credential_endpoint or f"https://{host}/ubag/verify"
+    doc = {
+        "ubag_version": "1.0",
+        "host": host,
+        "credential_endpoint": credential_endpoint,
+        "branches": {
+            "B-AGENT": {
+                "description": "Authorized MCP agents — receive clean JSON-LD structured data",
+                "requires": "X-UBAG-Credential header with valid JWT",
+                "content_type": "application/ld+json",
+            },
+            "A-HUMAN": {
+                "description": "Human browsers — transparently proxied to origin",
+                "requires": "None",
+            },
+            "C-SANDBOX": {
+                "description": "Unknown agents — Ed25519 nonce-signature challenge",
+                "requires": "None — solve challenge to get credentialed",
+                "challenge_endpoint": "/ubag/verify",
+            },
+        },
+        "discovery": {
+            "ubag_json": f"https://{host}/.well-known/ubag.json",
+            "verify_endpoint": f"https://{host}/ubag/verify",
+            "jwks_endpoint": f"https://{host}/.well-known/jwks.json",
+        },
+    }
+    if contact:
+        doc["contact"] = contact
+    if custom_fields:
+        doc.update(custom_fields)
+    return doc

ubag/_challenge.py

@@ -0,0 +1,111 @@
+"""
+Branch C — agent identity challenge (asymmetric).
+
+An unknown agent is issued a one-time nonce. It proves control of its identity
+key by signing the nonce with its Ed25519 PRIVATE key; the server verifies with
+the agent's PUBLIC key. That is what establishes *who* the agent is — knowledge
+of a shared secret never could.
+
+The nonce carries a server-side HMAC `stamp` so the server can confirm it issued
+the nonce without storing it (stateless issuance). That HMAC is the server signing
+to *itself* — it is not part of the identity proof.
+
+Replay: nonces are one-time. Provide a shared `store` (Redis/DB) in multi-process
+deployments; the in-memory default only protects a single process.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+import time
+from typing import Optional, Protocol
+
+from ubag._keys import agent_id, agent_verify
+
+
+class UBAGNonceStore(Protocol):
+    def exists(self, nonce: str) -> bool: ...
+    def mark_used(self, nonce: str) -> None: ...
+
+
+class _MemoryNonceStore:
+    def __init__(self) -> None:
+        self._used: set[str] = set()
+
+    def exists(self, nonce: str) -> bool:
+        return nonce in self._used
+
+    def mark_used(self, nonce: str) -> None:
+        self._used.add(nonce)
+
+
+_default_store = _MemoryNonceStore()
+
+
+def _stamp(server_secret: str, nonce: str, ts: int) -> str:
+    return hmac.new(
+        server_secret.encode(), f"{nonce}:{ts}".encode(), hashlib.sha256
+    ).hexdigest()
+
+
+def generate_challenge(server_secret: str, ttl: int = 120) -> dict:
+    """Generate a nonce challenge for an unknown agent (sent in the 429 body).
+
+    The agent must:
+      1. read `nonce`
+      2. sign the nonce bytes with its Ed25519 private key
+      3. POST {nonce, timestamp, stamp, agent_public, signature} to /ubag/verify
+    """
+    nonce = secrets.token_urlsafe(32)
+    ts = int(time.time())
+    return {
+        "nonce": nonce,
+        "timestamp": ts,
+        "ttl": ttl,
+        "algo": "Ed25519",
+        "stamp": _stamp(server_secret, nonce, ts),
+        "instructions": (
+            "Sign the `nonce` bytes with your Ed25519 private key and POST "
+            "{nonce, timestamp, stamp, agent_public, signature} to /ubag/verify."
+        ),
+    }
+
+
+def verify_challenge(
+    server_secret: str,
+    nonce: str,
+    timestamp: int,
+    stamp: str,
+    agent_public: str,
+    signature: str,
+    ttl: int = 120,
+    store: Optional[UBAGNonceStore] = None,
+) -> tuple[bool, str, Optional[str]]:
+    """Verify a challenge response. Returns (ok, reason, agent_id).
+
+    1. Replay   — nonce not already used
+    2. Stamp    — the server issued this exact (nonce, ts), untampered
+    3. Expiry   — within TTL
+    4. Identity — agent's signature over the nonce verifies under agent_public
+    """
+    nonce_store = store or _default_store
+
+    if not nonce or not agent_public or not signature:
+        return False, "missing_fields", None
+
+    if nonce_store.exists(nonce):
+        return False, "nonce_already_used", None
+
+    if not hmac.compare_digest(_stamp(server_secret, nonce, timestamp), stamp):
+        return False, "invalid_stamp", None
+
+    if int(time.time()) - timestamp > ttl:
+        return False, "nonce_expired", None
+
+    # The identity proof: only the holder of the matching private key can produce this.
+    if not agent_verify(agent_public, nonce.encode(), signature):
+        return False, "bad_signature", None
+
+    nonce_store.mark_used(nonce)
+    return True, "authorized", agent_id(agent_public)

ubag/_credential.py

@@ -0,0 +1,58 @@
+"""
+Credential issuance and validation (asymmetric, ES256).
+
+A credential is a short-lived JWT signed by the ISSUER's private key and verified
+with the issuer's PUBLIC key. Because verification needs only the public key
+(distributable via JWKS), any independent site can validate a credential without
+holding any secret — the OAuth/OIDC model.
+
+The credential is bound to the agent's identity key via the `cnf` (confirmation)
+claim, so a verifier can later require proof-of-possession of the agent key.
+"""
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+import jwt
+
+from ubag._keys import agent_id
+
+CREDENTIAL_HEADER = "X-UBAG-Credential"
+_DEFAULT_TTL = 300  # 5 minutes
+_ALG = "ES256"
+
+
+def issue_credential(
+    subject: str,
+    issuer_private_pem: str,
+    agent_public: Optional[str] = None,
+    agent_class: str = "authorized_agent",
+    ttl: int = _DEFAULT_TTL,
+    allowed_paths: list[str] | None = None,
+    issuer: str = "https://ubagprotocol.com",
+    kid: str = "ubag-issuer-1",
+) -> str:
+    """Mint a credential JWT signed with the issuer's EC P-256 private key (ES256)."""
+    now = int(time.time())
+    payload = {
+        "iss": issuer,
+        "sub": subject,
+        "iat": now,
+        "exp": now + ttl,
+        "agent_class": agent_class,
+        "paths": allowed_paths or ["/*"],
+    }
+    if agent_public:
+        # Bind the credential to the agent's identity key (key thumbprint).
+        payload["cnf"] = {"jkt": agent_id(agent_public), "pub": agent_public}
+    return jwt.encode(payload, issuer_private_pem, algorithm=_ALG, headers={"kid": kid})
+
+
+def validate_credential(token: str, issuer_public_pem: str) -> Optional[dict]:
+    """Return decoded claims if the credential is validly signed by the issuer,
+    else None. Verifies with the issuer's PUBLIC key — no shared secret."""
+    try:
+        return jwt.decode(token, issuer_public_pem, algorithms=[_ALG])
+    except jwt.PyJWTError:
+        return None

ubag/_keys.py

@@ -0,0 +1,119 @@
+"""
+Asymmetric key primitives for UBAG.
+
+Two key types, each chosen for a reason:
+
+* Agent identity  -> Ed25519. Raw 64-byte signatures, no DER/encoding ambiguity,
+  so an agent signature produced in Python verifies byte-for-byte in Node and
+  vice-versa. The agent's PUBLIC key is its identity.
+
+* Issuer (credential signing) -> EC P-256 / ES256 JWT. Chosen because it is the
+  one asymmetric JWT algorithm supported by BOTH PyJWT and Node's `jsonwebtoken`,
+  so a credential minted by either SDK verifies with the other via the issuer's
+  PUBLIC key (JWKS) — the OAuth/OIDC model. No shared secret, works across sites.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec, ed25519
+
+
+def _b64u(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).decode("ascii").rstrip("=")
+
+
+def _b64u_decode(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+# ── Agent identity keys (Ed25519) ──────────────────────────────────────────────
+
+def generate_agent_keypair() -> tuple[str, str]:
+    """Generate an agent identity keypair. Returns (private_b64url, public_b64url)
+    of the raw 32-byte Ed25519 keys."""
+    sk = ed25519.Ed25519PrivateKey.generate()
+    priv = sk.private_bytes(
+        serialization.Encoding.Raw,
+        serialization.PrivateFormat.Raw,
+        serialization.NoEncryption(),
+    )
+    pub = sk.public_key().public_bytes(
+        serialization.Encoding.Raw, serialization.PublicFormat.Raw
+    )
+    return _b64u(priv), _b64u(pub)
+
+
+def agent_sign(private_b64: str, message: bytes) -> str:
+    """Sign a message with an agent's Ed25519 private key. Returns b64url signature."""
+    sk = ed25519.Ed25519PrivateKey.from_private_bytes(_b64u_decode(private_b64))
+    return _b64u(sk.sign(message))
+
+
+def agent_verify(public_b64: str, message: bytes, signature_b64: str) -> bool:
+    """Verify an agent's Ed25519 signature over `message`. Never raises."""
+    try:
+        pk = ed25519.Ed25519PublicKey.from_public_bytes(_b64u_decode(public_b64))
+        pk.verify(_b64u_decode(signature_b64), message)
+        return True
+    except Exception:
+        return False
+
+
+def agent_id(public_b64: str) -> str:
+    """Stable agent identity derived from its public key (a key thumbprint).
+    This is what `sub` / `cnf` reference — identity is the key, not a claimed name."""
+    digest = hashlib.sha256(_b64u_decode(public_b64)).digest()
+    return "ubag:" + _b64u(digest)[:43]
+
+
+# ── Issuer keys (EC P-256, for ES256 credential JWTs) ──────────────────────────
+
+def generate_issuer_keypair() -> tuple[str, str]:
+    """Generate an issuer keypair for signing credentials.
+    Returns (private_pem, public_pem) for an EC P-256 key (ES256)."""
+    sk = ec.generate_private_key(ec.SECP256R1())
+    priv = sk.private_bytes(
+        serialization.Encoding.PEM,
+        serialization.PrivateFormat.PKCS8,
+        serialization.NoEncryption(),
+    ).decode("ascii")
+    pub = sk.public_key().public_bytes(
+        serialization.Encoding.PEM,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    ).decode("ascii")
+    return priv, pub
+
+
+def issuer_public_from_private(private_pem: str) -> str:
+    """Derive the issuer public PEM from its private PEM (so a site configured only
+    with the private key can also verify)."""
+    sk = serialization.load_pem_private_key(private_pem.encode("ascii"), password=None)
+    return sk.public_key().public_bytes(
+        serialization.Encoding.PEM,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    ).decode("ascii")
+
+
+def build_jwks(public_pem: str, kid: str = "ubag-issuer-1") -> dict:
+    """Build a JWKS document for the issuer's EC P-256 public key, so resource
+    servers can verify credentials by fetching /.well-known/jwks.json."""
+    pk = serialization.load_pem_public_key(public_pem.encode("ascii"))
+    nums = pk.public_numbers()
+    x = nums.x.to_bytes(32, "big")
+    y = nums.y.to_bytes(32, "big")
+    return {
+        "keys": [
+            {
+                "kty": "EC",
+                "crv": "P-256",
+                "x": _b64u(x),
+                "y": _b64u(y),
+                "use": "sig",
+                "alg": "ES256",
+                "kid": kid,
+            }
+        ]
+    }

ubag/_routing.py

@@ -0,0 +1,71 @@
+"""
+Three-branch routing matrix.
+
+Branch A — Human     → transparent proxy to origin
+Branch B — Agent     → clean JSON-LD structured data
+Branch C — Sandbox   → cryptographic challenge
+"""
+from __future__ import annotations
+
+import re
+from enum import Enum
+from typing import Optional
+
+
+class RoutingBranch(str, Enum):
+    HUMAN   = "A-HUMAN"
+    AGENT   = "B-AGENT"
+    SANDBOX = "C-SANDBOX"
+
+
+# HTTP library user-agent signatures — these are never human
+_MACHINE_UA = re.compile(
+    r"(python-httpx|python-requests|aiohttp|curl|wget|go-http-client|"
+    r"java\/|okhttp|axios|node-fetch|got\/|undici|libwww|mechanize|"
+    r"scrapy|selenium|playwright|puppeteer|headlesschrome|"
+    r"GPTBot|ClaudeBot|PerplexityBot|anthropic-ai|Googlebot|bingbot|"
+    r"DuckDuckBot|Baiduspider|YandexBot|facebookexternalhit|Twitterbot)",
+    re.IGNORECASE,
+)
+
+_BROWSER_ACCEPT = re.compile(r"text/html", re.IGNORECASE)
+_BROWSER_UA     = re.compile(r"Mozilla|Chrome|Safari|Firefox|Edge", re.IGNORECASE)
+
+
+def _is_machine(user_agent: str, accept: str) -> bool:
+    """
+    Heuristic: declared machine UA or missing browser Accept header.
+    Errs toward HUMAN for ambiguous traffic (fail open).
+    """
+    if _MACHINE_UA.search(user_agent):
+        return True
+    # UA claims to be a browser but sends no text/html Accept — likely a lib
+    if _BROWSER_UA.search(user_agent) and not _BROWSER_ACCEPT.search(accept):
+        return True
+    return False
+
+
+def resolve_branch(
+    user_agent: str,
+    accept: str,
+    credential_token: Optional[str],
+    validate_fn,
+) -> RoutingBranch:
+    """
+    Resolve which branch handles this request.
+
+    Args:
+        user_agent:       Value of User-Agent header
+        accept:           Value of Accept header
+        credential_token: Value of X-UBAG-Credential header (may be None)
+        validate_fn:      Callable[str] -> Optional[dict] — verifies the token
+    """
+    if credential_token:
+        claims = validate_fn(credential_token)
+        if claims:
+            return RoutingBranch.AGENT
+
+    if _is_machine(user_agent, accept):
+        return RoutingBranch.SANDBOX
+
+    return RoutingBranch.HUMAN

ubag/_sux.py

@@ -0,0 +1,48 @@
+"""
+Branch B — Structured UX (S-UX) response builder.
+
+Transforms site metadata into a clean JSON-LD payload for authorized agents.
+Agents get structured data in one request instead of scraping 50 pages.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+
+def build_jsonld_response(
+    host: str,
+    path: str,
+    site_meta: dict[str, Any],
+    agent_claims: dict,
+) -> dict:
+    """
+    Build a JSON-LD structured data response for Branch B agents.
+
+    Args:
+        host:        The requesting host (e.g. "example.com")
+        path:        The requested path (e.g. "/products/widget")
+        site_meta:   Developer-supplied metadata dict (see UBAGMiddleware.site_meta)
+        agent_claims: Decoded credential claims
+
+    Returns a JSON-LD compliant dict ready to serialize.
+    """
+    now = int(time.time())
+
+    base = {
+        "@context": "https://schema.org",
+        "@type": site_meta.get("type", "WebSite"),
+        "url": f"https://{host}{path}",
+        "name": site_meta.get("name", host),
+        "ubag:source": f"https://{host}",
+        "ubag:served_at": now,
+        "ubag:agent": agent_claims.get("sub", "unknown"),
+        "ubag:branch": "B-AGENT",
+    }
+
+    # Merge any developer-supplied schema.org fields
+    for key, value in site_meta.items():
+        if key not in ("type",):
+            base[key] = value
+
+    return base

ubag/agent.py

@@ -0,0 +1,90 @@
+"""
+AgentCredential — client-side helper for MCP agent developers.
+
+An agent's identity IS its Ed25519 keypair. To get into a UBAG-enabled site the
+agent solves the site's nonce challenge by signing it with its private key; the
+site (or central issuer) returns a credential the agent then carries.
+
+Usage:
+    from ubag import AgentCredential
+
+    agent = AgentCredential.generate(owner="me@example.com")   # once; persist agent.export()
+    # ... on a 429 challenge from a site:
+    solution = agent.solve_challenge(challenge)                 # POST to /ubag/verify
+    agent.set_credential(resp["credential"])                   # store what you get back
+    headers = agent.headers()                                   # attach to future requests
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ubag._credential import CREDENTIAL_HEADER
+from ubag._keys import agent_id, agent_sign, generate_agent_keypair
+
+
+class AgentCredential:
+    """Holds an agent's identity keypair and (once obtained) its credential token."""
+
+    def __init__(
+        self,
+        private_key: str,
+        public_key: str,
+        owner: str = "",
+        agent_class: str = "mcp_agent",
+    ) -> None:
+        self.private_key = private_key
+        self.public_key = public_key
+        self.owner = owner
+        self.agent_class = agent_class
+        self.agent_id = agent_id(public_key)
+        self._token: Optional[str] = None
+
+    @classmethod
+    def generate(cls, owner: str = "", agent_class: str = "mcp_agent") -> "AgentCredential":
+        """Create a brand-new agent identity (fresh Ed25519 keypair)."""
+        priv, pub = generate_agent_keypair()
+        return cls(private_key=priv, public_key=pub, owner=owner, agent_class=agent_class)
+
+    def export(self) -> dict[str, str]:
+        """Serialize the identity for persistence. Keep `private_key` secret."""
+        return {
+            "private_key": self.private_key,
+            "public_key": self.public_key,
+            "owner": self.owner,
+            "agent_class": self.agent_class,
+        }
+
+    @classmethod
+    def load(cls, data: dict) -> "AgentCredential":
+        return cls(
+            private_key=data["private_key"],
+            public_key=data["public_key"],
+            owner=data.get("owner", ""),
+            agent_class=data.get("agent_class", "mcp_agent"),
+        )
+
+    def solve_challenge(self, challenge: dict) -> dict:
+        """Sign a site's nonce challenge. Returns the body to POST to /ubag/verify."""
+        nonce = challenge["nonce"]
+        return {
+            "nonce": nonce,
+            "timestamp": challenge["timestamp"],
+            "stamp": challenge["stamp"],
+            "agent_public": self.public_key,
+            "signature": agent_sign(self.private_key, nonce.encode()),
+        }
+
+    def set_credential(self, token: str) -> None:
+        """Store the credential returned by /ubag/verify."""
+        self._token = token
+
+    def headers(self) -> dict[str, str]:
+        """Headers to attach to requests once a credential has been obtained."""
+        if not self._token:
+            raise RuntimeError(
+                "No credential yet — solve a site challenge and call set_credential() first."
+            )
+        return {CREDENTIAL_HEADER: self._token}
+
+    def __repr__(self) -> str:
+        return f"AgentCredential(agent_id={self.agent_id!r}, agent_class={self.agent_class!r})"

ubag/middleware/fastapi.py

@@ -0,0 +1,307 @@
+"""
+FastAPI / Starlette ASGI middleware.
+
+Usage:
+    from fastapi import FastAPI
+    from ubag import UBAGMiddleware, generate_issuer_keypair
+
+    issuer_private, _ = generate_issuer_keypair()   # EC P-256 (ES256)
+
+    app = FastAPI()
+    app.add_middleware(
+        UBAGMiddleware,
+        origin="https://yoursite.com",
+        issuer_key=issuer_private,                  # mints + verifies credentials
+        site_meta={
+            "name": "My Store",
+            "type": "Store",
+            "description": "We sell widgets",
+        },
+    )
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from typing import Any, Callable, Optional
+
+import httpx
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from ubag._agents_json import build_agents_json
+from ubag._challenge import generate_challenge, verify_challenge
+from ubag._credential import CREDENTIAL_HEADER, issue_credential, validate_credential
+from ubag._keys import build_jwks, issuer_public_from_private
+from ubag._routing import RoutingBranch, resolve_branch
+from ubag._sux import build_jsonld_response
+
+
+class UBAGMiddleware(BaseHTTPMiddleware):
+    """
+    UBAG three-branch routing middleware for FastAPI / Starlette.
+
+    Args:
+        app:                  The ASGI application to wrap.
+        origin:               The upstream origin URL (Branch A proxy target).
+                              e.g. "https://yoursite.com" or "https://192.168.1.1"
+        secret_key:           HMAC/JWT secret. Must match credentials issued to agents.
+                              Defaults to UBAG_SECRET_KEY env var.
+        site_meta:            Schema.org metadata served to Branch B agents.
+                              Keys map directly to JSON-LD fields.
+        credential_endpoint:  URL where agents obtain credentials.
+        audit_fn:             Optional callback(branch, request, response) for logging.
+        on_verified:          Optional callback(claims, request) when a challenge is solved.
+    """
+
+    def __init__(
+        self,
+        app,
+        origin: str = "",
+        issuer_key: str = "",
+        issuer_public_key: str = "",
+        server_secret: str = "",
+        site_meta: dict[str, Any] | None = None,
+        credential_endpoint: str = "",
+        audit_fn: Optional[Callable] = None,
+        on_verified: Optional[Callable] = None,
+    ) -> None:
+        super().__init__(app)
+        self.origin              = origin.rstrip("/")
+        # Issuer private key (EC P-256 PEM) lets this site MINT credentials; the public
+        # key (derived from it) is used to VERIFY. A verify-only site can pass
+        # issuer_public_key alone — no secret required to validate, the OAuth/JWKS model.
+        self.issuer_private      = issuer_key or os.getenv("UBAG_ISSUER_KEY", "")
+        if self.issuer_private:
+            self.issuer_public = issuer_public_from_private(self.issuer_private)
+        else:
+            self.issuer_public = issuer_public_key or os.getenv("UBAG_ISSUER_PUBLIC", "")
+        # HMAC key for stateless nonce stamping — the server signing to itself.
+        self.server_secret       = (
+            server_secret or os.getenv("UBAG_SERVER_SECRET")
+            or hashlib.sha256((self.issuer_private or "ubag-stamp").encode()).hexdigest()
+        )
+        self.site_meta           = site_meta or {}
+        self.credential_endpoint = credential_endpoint
+        self.audit_fn            = audit_fn
+        self.on_verified         = on_verified
+
+        self._http_client: httpx.AsyncClient | None = None
+
+    # ------------------------------------------------------------------
+    # Middleware entry point
+    # ------------------------------------------------------------------
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        path = request.url.path
+
+        # UBAG system paths — handled here, never forwarded
+        if path in ("/.well-known/ubag.json", "/agents.json"):  # /agents.json = legacy alias
+            return self._ubag_json_response(request)
+        if path == "/.well-known/jwks.json":
+            return self._jwks_response()
+        if path == "/ubag/verify":
+            return await self._handle_verify(request)
+
+        # Routing
+        ua         = request.headers.get("user-agent", "")
+        accept     = request.headers.get("accept", "")
+        cred_token = request.headers.get(CREDENTIAL_HEADER.lower()) or \
+                     request.headers.get(CREDENTIAL_HEADER)
+
+        branch = resolve_branch(
+            user_agent=ua,
+            accept=accept,
+            credential_token=cred_token,
+            validate_fn=lambda t: validate_credential(t, self.issuer_public),
+        )
+
+        if branch == RoutingBranch.AGENT:
+            response = self._branch_b(request, cred_token)
+        elif branch == RoutingBranch.SANDBOX:
+            response = self._branch_c(request)
+        else:
+            if self.origin:
+                response = await self._branch_a(request)
+            else:
+                response = await call_next(request)
+
+        if self.audit_fn:
+            try:
+                self.audit_fn(branch, request, response)
+            except Exception:
+                pass
+
+        return response
+
+    # ------------------------------------------------------------------
+    # Branch B — Authorized agent → JSON-LD
+    # ------------------------------------------------------------------
+
+    def _branch_b(self, request: Request, token: str) -> JSONResponse:
+        claims  = validate_credential(token, self.issuer_public)
+        host    = request.headers.get("host", "").split(":")[0]
+        payload = build_jsonld_response(
+            host=host,
+            path=request.url.path,
+            site_meta=self.site_meta,
+            agent_claims=claims or {},
+        )
+        return JSONResponse(
+            content=payload,
+            media_type="application/ld+json",
+            headers={
+                "X-UBAG-Branch": "B-AGENT",
+                CREDENTIAL_HEADER: token,
+            },
+        )
+
+    # ------------------------------------------------------------------
+    # Branch A — Human → transparent proxy to origin
+    # ------------------------------------------------------------------
+
+    async def _branch_a(self, request: Request) -> Response:
+        client = self._get_http_client()
+        full_path = request.url.path
+        url = f"{self.origin}/{full_path.lstrip('/')}"
+        if request.url.query:
+            url += f"?{request.url.query}"
+
+        skip = {"connection", "transfer-encoding", "te", "trailer", "upgrade"}
+        headers = {k: v for k, v in request.headers.items() if k.lower() not in skip}
+        # Preserve original Host so shared hosting serves the right site
+        headers["host"] = request.headers.get("host", "").split(":")[0]
+        headers["x-forwarded-for"]   = request.client.host if request.client else "unknown"
+        headers["x-forwarded-proto"] = "https"
+
+        body = await request.body()
+        resp = await client.request(
+            method=request.method,
+            url=url,
+            headers=headers,
+            content=body,
+        )
+
+        skip_resp = {"transfer-encoding", "connection", "keep-alive", "upgrade"}
+        resp_headers = {k: v for k, v in resp.headers.items() if k.lower() not in skip_resp}
+        resp_headers["X-UBAG-Branch"] = "A-HUMAN"
+
+        return Response(
+            content=resp.content,
+            status_code=resp.status_code,
+            headers=resp_headers,
+            media_type=resp.headers.get("content-type"),
+        )
+
+    # ------------------------------------------------------------------
+    # Branch C — Unknown agent → sandbox challenge
+    # ------------------------------------------------------------------
+
+    def _branch_c(self, request: Request) -> JSONResponse:
+        challenge = generate_challenge(self.server_secret)
+        return JSONResponse(
+            status_code=429,
+            content={
+                "status": "challenge_required",
+                "ubag_challenge": challenge,
+            },
+            headers={"X-UBAG-Branch": "C-SANDBOX"},
+        )
+
+    # ------------------------------------------------------------------
+    # /ubag/verify — agent submits challenge solution
+    # ------------------------------------------------------------------
+
+    async def _handle_verify(self, request: Request) -> JSONResponse:
+        from ubag._challenge import verify_challenge
+
+        try:
+            body = await request.json()
+        except Exception:
+            return JSONResponse(status_code=400, content={"error": "invalid_json"})
+
+        ok, reason, aid = verify_challenge(
+            server_secret=self.server_secret,
+            nonce=body.get("nonce", ""),
+            timestamp=int(body.get("timestamp", 0)),
+            stamp=body.get("stamp", ""),
+            agent_public=body.get("agent_public", ""),
+            signature=body.get("signature", ""),
+        )
+
+        if not ok:
+            return JSONResponse(status_code=403, content={"status": "failed", "reason": reason})
+
+        if not self.issuer_private:
+            # Identity proven, but this site doesn't mint credentials itself —
+            # point the agent at the central issuer.
+            return JSONResponse(status_code=200, content={
+                "status": "verified",
+                "agent_id": aid,
+                "credential_endpoint": self.credential_endpoint,
+                "message": "Identity verified. Obtain a credential from credential_endpoint.",
+            })
+
+        token = issue_credential(
+            subject=aid,
+            issuer_private_pem=self.issuer_private,
+            agent_public=body.get("agent_public", ""),
+        )
+
+        if self.on_verified:
+            try:
+                claims = validate_credential(token, self.issuer_public)
+                self.on_verified(claims, request)
+            except Exception:
+                pass
+
+        return JSONResponse(
+            status_code=200,
+            content={
+                "status": "authorized",
+                "credential": token,
+                "header": CREDENTIAL_HEADER,
+                "instructions": f"Include '{CREDENTIAL_HEADER}: {token}' in all future requests.",
+            },
+        )
+
+    # ------------------------------------------------------------------
+    # /.well-known/ubag.json  (alias: /agents.json) — discovery document
+    # ------------------------------------------------------------------
+
+    def _ubag_json_response(self, request: Request) -> JSONResponse:
+        host = request.headers.get("host", "").split(":")[0]
+        doc  = build_agents_json(
+            host=host,
+            credential_endpoint=self.credential_endpoint,
+        )
+        return JSONResponse(content=doc, headers={"X-UBAG-Branch": "META"})
+
+    # ------------------------------------------------------------------
+    # /.well-known/jwks.json — issuer public key, so any site can verify
+    # this issuer's credentials without holding a secret (OAuth/OIDC model)
+    # ------------------------------------------------------------------
+
+    def _jwks_response(self) -> JSONResponse:
+        if not self.issuer_public:
+            return JSONResponse(status_code=404, content={"error": "no_issuer_key"})
+        return JSONResponse(
+            content=build_jwks(self.issuer_public),
+            headers={"X-UBAG-Branch": "META", "Cache-Control": "public, max-age=3600"},
+        )
+
+    # ------------------------------------------------------------------
+    # Shared HTTP client for Branch A
+    # ------------------------------------------------------------------
+
+    def _get_http_client(self) -> httpx.AsyncClient:
+        if self._http_client is None or self._http_client.is_closed:
+            self._http_client = httpx.AsyncClient(
+                follow_redirects=True,
+                timeout=30,
+                verify=False,
+                limits=httpx.Limits(max_connections=100, max_keepalive_connections=20),
+            )
+        return self._http_client

ubag-0.2.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: ubag
+Version: 0.2.0
+Summary: Agent identity and routing middleware for MCP-compatible agents
+Author: Mohamed Ben Hadj Hmida
+License-Expression: MIT
+Project-URL: Homepage, https://ubagprotocol.com
+Project-URL: Repository, https://github.com/mohameduk/Ubag_protocol
+Keywords: mcp,agents,ai,middleware,routing,bot-detection
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyJWT[crypto]>=2.8.0
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.111.0; extra == "fastapi"
+Requires-Dist: starlette>=0.37.0; extra == "fastapi"
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: flask
+Requires-Dist: flask>=3.0; extra == "flask"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: fastapi>=0.111.0; extra == "dev"
+Requires-Dist: starlette>=0.37.0; extra == "dev"
+Dynamic: license-file
+
+# 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 bots to a cryptographic challenge. 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](https://github.com/mohameduk/Ubag_protocol#readme) and
+> [SECURITY.md](https://github.com/mohameduk/Ubag_protocol/blob/main/SECURITY.md).
+
+## Install
+
+```bash
+pip install "ubag[fastapi]"
+```
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+from ubag import UBAGMiddleware, generate_issuer_keypair
+
+issuer_private, _ = generate_issuer_keypair()   # EC P-256 (ES256)
+
+app = FastAPI()
+app.add_middleware(
+    UBAGMiddleware,
+    origin="https://yoursite.com",
+    issuer_key=issuer_private,                  # mints + verifies credentials
+    site_meta={"name": "My Store", "type": "Store", "description": "We sell widgets"},
+)
+```
+
+Your site now serves clean JSON-LD to credentialed agents, proxies humans to your
+origin, challenges unknown bots, exposes `/.well-known/ubag.json` for discovery,
+and serves its issuer key as JWKS at `/.well-known/jwks.json`.
+
+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.

ubag-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+ubag/__init__.py,sha256=rD-for6Vz864AUTzgeV0gV3JLQJhcGnZ0bsPblVjWOg,1293
+ubag/_agents_json.py,sha256=eaq0RsKUQx_ArllBisbGOEloPyHh6ziUQ_QBcpjvo-8,2319
+ubag/_challenge.py,sha256=GEXb5ni33UkKZMdtvbZrifM7oTVll5K76mU4dy3V78o,3513
+ubag/_credential.py,sha256=8T_tPreL6wx910rJ1orMXg0MdA-gnDeUN8ryiaH58z4,1970
+ubag/_keys.py,sha256=Opw5rlSYw-7HR2y1a4i4K_MD7YP5-0ywp0Xx4sgWJP4,4477
+ubag/_routing.py,sha256=3GpCuGMHv05AXY8j26V_NsGLWoa81be1WqYjpEcFMoc,2160
+ubag/_sux.py,sha256=PBudq9_7xf1lkcUsW4CE6m52jCqi-wqzRHVLS9JvV4I,1393
+ubag/agent.py,sha256=73u_F9LgWju8Osp4T1rqrJb3J76DJe26Cp3CugfxS8I,3413
+ubag/middleware/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ubag/middleware/fastapi.py,sha256=0RXu8YTgrtqZ2BljHbz7C3fYQm0RBfDSLzOJ4O_kRck,12210
+ubag-0.2.0.dist-info/licenses/LICENSE,sha256=1-GTGJfWAuz01QvGmwkJSmGdw_-0gW4G51PaL35j-go,1079
+ubag-0.2.0.dist-info/METADATA,sha256=VcsJmmqile-VSitJ4N-go6lJvnnj3Rns-YLg2b8YXAw,3117
+ubag-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ubag-0.2.0.dist-info/top_level.txt,sha256=rmnswtqQiKrkm0JMFDK8aA8BT1C3L3Ofi6V5-hIlC0k,5
+ubag-0.2.0.dist-info/RECORD,,

ubag-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ubag-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Ben Hadj Hmida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ubag-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ubag