ubag 0.2.0__tar.gz

ubag-0.2.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,46 @@
+# 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/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ubag"
+version = "0.2.0"
+description = "Agent identity and routing middleware for MCP-compatible agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Mohamed Ben Hadj Hmida" }]
+keywords = ["mcp", "agents", "ai", "middleware", "routing", "bot-detection"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Topic :: Security",
+]
+dependencies = [
+    "PyJWT[crypto]>=2.8.0",
+    "cryptography>=42.0",
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.111.0", "starlette>=0.37.0"]
+django = ["django>=4.2"]
+flask = ["flask>=3.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "httpx>=0.27.0",
+    "fastapi>=0.111.0",
+    "starlette>=0.37.0",
+]
+
+[project.urls]
+Homepage = "https://ubagprotocol.com"
+Repository = "https://github.com/mohameduk/Ubag_protocol"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

ubag-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ubag-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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