regent-httpsig 0.1.0__py3-none-any.whl

regent_httpsig/__init__.py

@@ -0,0 +1,31 @@
+"""regent-httpsig — verify and sign AI agent HTTP traffic (RFC 9421).
+
+Web Bot Auth (what OpenAI ships, what Cloudflare/AWS/Google verify) and AAuth
+(draft-hardt), in plain Python. See https://github.com/regent-protocol/regent-httpsig
+"""
+
+from regent_httpsig.config import HttpsigConfig
+from regent_httpsig.jwk import b64url, jwk_thumbprint, load_ed25519_jwk
+from regent_httpsig.netguard import NotPublicURL, assert_public_url
+from regent_httpsig.sfv import parse_signature_agent
+from regent_httpsig.sign import DIRECTORY_MEDIA_TYPE, EgressSigner, generate_seed
+from regent_httpsig.verify import WBA_TAG, HttpsigVerifier, VerifiedSignature
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DIRECTORY_MEDIA_TYPE",
+    "EgressSigner",
+    "HttpsigConfig",
+    "HttpsigVerifier",
+    "NotPublicURL",
+    "VerifiedSignature",
+    "WBA_TAG",
+    "__version__",
+    "assert_public_url",
+    "b64url",
+    "generate_seed",
+    "jwk_thumbprint",
+    "load_ed25519_jwk",
+    "parse_signature_agent",
+]

regent_httpsig/cli.py

@@ -0,0 +1,55 @@
+"""``regent-httpsig keygen`` — generate an agent key + ready-to-publish directory."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from regent_httpsig.sign import EgressSigner, generate_seed
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="regent-httpsig",
+        description="Utilities for RFC 9421 agent signatures (Web Bot Auth / AAuth).",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    keygen = sub.add_parser(
+        "keygen",
+        help="Generate an Ed25519 agent key and the well-known directory files.",
+    )
+    keygen.add_argument(
+        "--agent", default="https://myagent.example",
+        help="Your agent's origin (where you will host the key directory).",
+    )
+    keygen.add_argument(
+        "--out", type=Path, default=None,
+        help="Directory to write http-message-signatures-directory + jwks.json into.",
+    )
+    args = parser.parse_args(argv)
+
+    if args.command == "keygen":
+        seed = generate_seed()
+        signer = EgressSigner(seed=seed, signature_agent=args.agent)
+        directory = json.dumps(signer.directory(), indent=2)
+        print("# Keep this secret — it IS your agent's identity:", file=sys.stderr)
+        print(f"AGENT_KEY_SEED={seed}")
+        print(f"# keyid (RFC 7638 thumbprint): {signer.keyid}", file=sys.stderr)
+        if args.out:
+            args.out.mkdir(parents=True, exist_ok=True)
+            (args.out / "http-message-signatures-directory").write_text(directory)
+            (args.out / "jwks.json").write_text(directory)
+            print(
+                f"# Wrote {args.out}/http-message-signatures-directory and jwks.json\n"
+                f"# Serve them at {args.agent}/.well-known/",
+                file=sys.stderr,
+            )
+        else:
+            print(directory, file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

regent_httpsig/config.py

@@ -0,0 +1,32 @@
+"""Verifier configuration — a plain frozen dataclass, no framework coupling."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+__all__ = ["HttpsigConfig"]
+
+
+@dataclass(frozen=True)
+class HttpsigConfig:
+    """Configuration for :class:`regent_httpsig.HttpsigVerifier`.
+
+    Defaults are production-safe: https-only directory fetching over public IPs,
+    bounded cache, 25-hour max signature age (Web Bot Auth signatures carry
+    ``created``/``expires``; 25h tolerates a day of clock drift)."""
+
+    # Origins/issuers you additionally mark as trusted (``VerifiedSignature.trusted``).
+    # Verification itself never depends on this — it only annotates the result.
+    trusted_agents: frozenset[str] = field(default_factory=frozenset)
+    # Reject signatures created earlier than this many hours ago.
+    max_age_hours: int = 25
+    # Key-directory cache TTL (seconds); failures are cached for negative_cache_ttl.
+    cache_ttl: float = 600.0
+    negative_cache_ttl: float = 120.0
+    cache_max_entries: int = 256
+    # Directory fetching: timeout, response size cap, redirects are never followed.
+    fetch_timeout: float = 5.0
+    max_directory_bytes: int = 64 * 1024
+    # Hosts exempt from the https-only + public-IP SSRF guard (local dev only —
+    # e.g. frozenset({"localhost"})). Leave empty in production.
+    insecure_hosts: frozenset[str] = field(default_factory=frozenset)

regent_httpsig/fastapi.py

@@ -0,0 +1,94 @@
+"""FastAPI integration — the 5-line path (requires the ``[fastapi]`` extra).
+
+Usage::
+
+    from regent_httpsig import HttpsigVerifier
+    from regent_httpsig.fastapi import attach, SignatureDep, VerifiedSignature
+
+    app = FastAPI()
+    attach(app, HttpsigVerifier())
+
+    @app.post("/v1/orders")
+    async def create_order(sig: VerifiedSignature | None = SignatureDep):
+        if sig:
+            ...  # sig.agent == "https://chatgpt.com", sig.keyid, sig.trusted
+
+``SignatureDep`` is enrichment: ``None`` when absent/invalid, never raises.
+``RequiredSignatureDep`` is authentication: a coded 401 tells the agent exactly
+how to sign.
+
+Proxy note: the signer signed the PUBLIC url. Behind a reverse proxy this
+dependency rebuilds it from ``X-Forwarded-Proto`` + ``Host`` — make sure your
+proxy sets ``X-Forwarded-Proto`` (nginx: ``proxy_set_header X-Forwarded-Proto
+$scheme;``), or verification will fail on the scheme mismatch.
+"""
+
+from __future__ import annotations
+
+from fastapi import Depends, FastAPI, HTTPException, Request
+
+from regent_httpsig.verify import HttpsigVerifier, VerifiedSignature
+
+__all__ = ["RequiredSignatureDep", "SignatureDep", "VerifiedSignature", "attach"]
+
+_STATE_ATTR = "regent_httpsig_verifier"
+
+
+def attach(app: FastAPI, verifier: HttpsigVerifier) -> None:
+    """Register the verifier on the app; the dependencies below read it back."""
+    setattr(app.state, _STATE_ATTR, verifier)
+
+
+def _public_url(request: Request) -> str:
+    """Rebuild the URL the signer signed: scheme from the proxy, authority from
+    Host — an ASGI server behind a proxy would otherwise see http://<container>."""
+    host = request.headers.get("host") or request.url.netloc
+    scheme = request.headers.get("x-forwarded-proto") or request.url.scheme
+    path = request.url.path
+    query = f"?{request.url.query}" if request.url.query else ""
+    return f"{scheme}://{host}{path}{query}"
+
+
+async def get_signature(request: Request) -> VerifiedSignature | None:
+    """Optional verification: zero-cost without a Signature header, never raises."""
+    verifier: HttpsigVerifier | None = getattr(request.app.state, _STATE_ATTR, None)
+    if verifier is None:
+        raise RuntimeError(
+            "regent-httpsig verifier not attached — call "
+            "regent_httpsig.fastapi.attach(app, HttpsigVerifier()) at startup"
+        )
+    if "signature" not in request.headers:
+        return None
+    cached = getattr(request.state, "regent_httpsig_result", "unset")
+    if cached != "unset":
+        return cached  # type: ignore[return-value]
+    result = await verifier.verify(
+        request.method, _public_url(request), dict(request.headers)
+    )
+    request.state.regent_httpsig_result = result
+    return result
+
+
+async def require_signature(request: Request) -> VerifiedSignature:
+    """Hard requirement: a fully verified signature, or a 401 that tells the
+    agent exactly how to sign."""
+    sig = await get_signature(request)
+    if sig is None:
+        raise HTTPException(
+            status_code=401,
+            detail={
+                "code": "SIGNATURE_REQUIRED",
+                "message": (
+                    "Sign this request with RFC 9421 HTTP Message Signatures: either "
+                    'Web Bot Auth (tag="web-bot-auth", Ed25519 key published at '
+                    "{your-origin}/.well-known/http-message-signatures-directory, "
+                    "Signature-Agent header naming that origin) or AAuth (agent_token "
+                    "in the Signature-Key header, signature bound to its cnf.jwk)."
+                ),
+            },
+        )
+    return sig
+
+
+SignatureDep = Depends(get_signature)
+RequiredSignatureDep = Depends(require_signature)

regent_httpsig/jwk.py

@@ -0,0 +1,46 @@
+"""JWK helpers — RFC 7638 thumbprints (RFC 8037 A.3 for Ed25519) and key loading."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from typing import Any
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+__all__ = ["b64url", "b64url_decode", "jwk_thumbprint", "load_ed25519_jwk"]
+
+
+def b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
+
+
+def b64url_decode(data: str) -> bytes:
+    return base64.urlsafe_b64decode(data + "=" * (-len(data) % 4))
+
+
+def jwk_thumbprint(jwk: dict[str, Any]) -> str:
+    """RFC 7638 JWK thumbprint (RFC 8037 A.3 for OKP): sha256 over the canonical
+    JSON of the required members, base64url without padding.
+
+    This is the keyid form Web Bot Auth uses — e.g. the RFC test key's thumbprint
+    is ``poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U``."""
+    required_by_kty = {
+        "OKP": ("crv", "kty", "x"),
+        "EC": ("crv", "kty", "x", "y"),
+        "RSA": ("e", "kty", "n"),
+    }
+    members = required_by_kty.get(str(jwk.get("kty", "")))
+    if not members:
+        raise ValueError(f"unsupported kty {jwk.get('kty')!r}")
+    canonical = json.dumps(
+        {m: jwk[m] for m in sorted(members)}, separators=(",", ":"), sort_keys=True
+    )
+    return b64url(hashlib.sha256(canonical.encode()).digest())
+
+
+def load_ed25519_jwk(jwk: dict[str, Any]) -> Ed25519PublicKey:
+    if jwk.get("kty") != "OKP" or jwk.get("crv") != "Ed25519" or "x" not in jwk:
+        raise ValueError("only OKP/Ed25519 JWKs are supported")
+    return Ed25519PublicKey.from_public_bytes(b64url_decode(str(jwk["x"])))

regent_httpsig/netguard.py

@@ -0,0 +1,62 @@
+"""SSRF guard for identity-document fetching.
+
+The verifier fetches key directories from attacker-nameable origins (whoever
+signs a request chooses its ``Signature-Agent`` / ``iss``). Without a guard,
+a malicious signer could point the verifier at internal services
+(``http://redis:6379``, the cloud metadata IP ``169.254.169.254``, loopback,
+other containers) and use your API as a proxy into your private network.
+
+Every resolved address must be public; the check resolves (not just parses),
+which also catches DNS names that map to private IPs."""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import socket
+from urllib.parse import urlparse
+
+__all__ = ["NotPublicURL", "assert_public_url"]
+
+
+class NotPublicURL(ValueError):
+    """The URL does not resolve to an exclusively-public address."""
+
+
+def _is_public(ip: str) -> bool:
+    try:
+        addr = ipaddress.ip_address(ip)
+    except ValueError:
+        return False
+    return not (
+        addr.is_private
+        or addr.is_loopback
+        or addr.is_link_local
+        or addr.is_reserved
+        or addr.is_multicast
+        or addr.is_unspecified
+    )
+
+
+async def assert_public_url(url: str, allow_hosts: frozenset[str] = frozenset()) -> None:
+    """Raise :class:`NotPublicURL` unless ``url`` is http(s) to an allow-listed
+    host or a host whose EVERY resolved address is public."""
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise NotPublicURL(f"unsupported scheme {parsed.scheme!r}")
+    host = parsed.hostname or ""
+    if not host:
+        raise NotPublicURL("URL has no host")
+    if host in allow_hosts:
+        return
+    try:
+        infos = await asyncio.to_thread(
+            socket.getaddrinfo, host, parsed.port or None, 0, socket.SOCK_STREAM
+        )
+    except socket.gaierror as exc:
+        raise NotPublicURL(f"cannot resolve host {host!r}") from exc
+    ips = {str(info[4][0]) for info in infos}
+    if not ips or any(not _is_public(ip) for ip in ips):
+        raise NotPublicURL(
+            f"host {host!r} resolves to a private/loopback/link-local address"
+        )

regent_httpsig/sfv.py

@@ -0,0 +1,132 @@
+"""RFC 9421 plumbing over the ``http-message-signatures`` library.
+
+Contains the pieces the upstream library is missing for the AI-agent profiles:
+
+- :class:`DictKeyComponentResolver` — RFC 9421 §2.1.2 ``;key=`` dictionary-member
+  selection (needed for the current Web Bot Auth ``"signature-agent";key="agent2"``
+  covered component; upstream resolves whole header values only).
+- :func:`parse_signature_agent` — both wire forms of ``Signature-Agent``:
+  the draft -05 sf-dictionary AND the legacy bare sf-string OpenAI ships today.
+- :class:`Message` / :class:`StaticKeyResolver` — the minimal request shape and
+  key resolution the verifier needs.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from http_message_signatures import (  # type: ignore[attr-defined]
+    HTTPSignatureComponentResolver,
+    HTTPSignatureKeyResolver,
+    algorithms,
+    http_sfv,
+)
+from http_message_signatures.structures import CaseInsensitiveDict
+
+__all__ = [
+    "ED25519",
+    "CaseInsensitiveDict",
+    "DictKeyComponentResolver",
+    "Message",
+    "SFDictionary",
+    "SFItem",
+    "StaticKeyResolver",
+    "parse_signature_agent",
+    "parse_signature_key_header",
+]
+
+# The library ships no explicit re-exports (strict mypy: attr-defined) — alias once.
+SFDictionary = http_sfv.Dictionary  # type: ignore[attr-defined]
+SFItem = http_sfv.Item  # type: ignore[attr-defined]
+ED25519 = algorithms.ED25519  # type: ignore[attr-defined]
+
+
+class Message:
+    """The minimal request shape http-message-signatures needs (.method/.url/.headers).
+
+    ``headers`` is wrapped in the library's own case-insensitive mapping — ASGI
+    frameworks lowercase header names, and the upstream verifier looks up
+    ``Signature-Input`` case-sensitively."""
+
+    def __init__(self, method: str, url: str, headers: dict[str, str]):
+        self.method = method
+        self.url = url
+        self.headers = CaseInsensitiveDict(headers)  # type: ignore[no-untyped-call]
+
+
+class DictKeyComponentResolver(HTTPSignatureComponentResolver):
+    """Adds RFC 9421 §2.1.2 ``;key=`` dictionary-member selection for header
+    components (the upstream resolver returns the whole header value only).
+    Needed for the current Web Bot Auth form: ``"signature-agent";key="agent2"``
+    must resolve to the serialized member value (e.g. ``"https://…"``)."""
+
+    def resolve(self, component_node: Any) -> Any:  # http_sfv Item (untyped lib)
+        component_id = str(component_node.value)
+        key = component_node.params.get("key")
+        if key is not None and not component_id.startswith("@"):
+            if component_id not in self.headers:
+                raise ValueError(f'covered header "{component_id}" not in message')
+            node = SFDictionary()
+            node.parse(self.headers[component_id].encode())
+            if key not in node:
+                raise ValueError(f'member "{key}" not in dictionary header "{component_id}"')
+            return str(node[key])
+        return super().resolve(component_node)
+
+
+class StaticKeyResolver(HTTPSignatureKeyResolver):
+    """Resolves keyids from a prefetched map; ``default`` (AAuth cnf.jwk) wins
+    when the map has no entry — the possession key comes from the token, not
+    from the wire keyid."""
+
+    def __init__(
+        self,
+        keys: dict[str, Ed25519PublicKey],
+        default: Ed25519PublicKey | None = None,
+    ):
+        self._keys = keys
+        self._default = default
+
+    def resolve_public_key(self, key_id: str) -> Ed25519PublicKey:
+        key = self._keys.get(key_id, self._default)
+        if key is None:
+            raise ValueError(f"unknown keyid {key_id!r}")
+        return key
+
+    def resolve_private_key(self, key_id: str) -> Any:
+        raise NotImplementedError
+
+
+def parse_signature_agent(value: str) -> str | None:
+    """Extract the directory origin from ``Signature-Agent`` — sf-dictionary
+    (draft -05) or bare sf-string (legacy, what OpenAI sends)."""
+    value = value.strip()
+    if not value:
+        return None
+    try:
+        if value.startswith('"'):
+            item = SFItem()
+            item.parse(value.encode())
+            return str(item.value)
+        node = SFDictionary()
+        node.parse(value.encode())
+        for member in node.values():
+            return str(member.value)
+    except Exception:  # noqa: BLE001 — malformed header = no directory
+        return None
+    return None
+
+
+def parse_signature_key_header(value: str) -> tuple[str, str] | None:
+    """``Signature-Key: sig=jwt;jwt="eyJ…"`` → (label, jwt) — the AAuth carrier."""
+    try:
+        node = SFDictionary()
+        node.parse(value.encode())
+        for label, member in node.items():
+            jwt_param = member.params.get("jwt")
+            if jwt_param:
+                return str(label), str(jwt_param)
+    except Exception:  # noqa: BLE001
+        return None
+    return None

regent_httpsig/sign.py

@@ -0,0 +1,121 @@
+"""Outbound RFC 9421 signing (Web Bot Auth) — give your agent a verifiable identity.
+
+Sign every request your agent makes with an Ed25519 key whose public half you
+publish at ``{signature_agent}/.well-known/http-message-signatures-directory``.
+Verifiers that speak Web Bot Auth (Cloudflare, AWS WAF, Vercel, this library…)
+then see a *signed agent* instead of an anonymous bot.
+
+The ``Signature-Agent`` header is emitted in the LEGACY sf-string form
+(``"https://…"``) — the form OpenAI ships in production, accepted by every
+deployed verifier today; the draft -05 sf-dictionary form still has patchy
+support.
+
+Unlike a service-level integration, this library FAILS LOUD: a bad seed raises
+at construction and a signing error raises from :meth:`EgressSigner.sign`.
+Wrap in try/except yourself if your egress path must never break on signing.
+"""
+
+from __future__ import annotations
+
+import secrets
+from datetime import datetime, timedelta
+from typing import Any
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from http_message_signatures import (  # type: ignore[attr-defined]
+    HTTPMessageSigner,
+    HTTPSignatureKeyResolver,
+)
+
+from regent_httpsig.jwk import b64url, b64url_decode, jwk_thumbprint
+from regent_httpsig.sfv import ED25519, Message
+
+__all__ = ["DIRECTORY_MEDIA_TYPE", "EgressSigner", "generate_seed"]
+
+DIRECTORY_MEDIA_TYPE = "application/http-message-signatures-directory+json"
+_DEFAULT_COVERED = ("@method", "@authority", "@path", "signature-agent")
+
+
+def generate_seed() -> str:
+    """A fresh Ed25519 seed, base64url-encoded — store it like any secret."""
+    return b64url(secrets.token_bytes(32))
+
+
+class _Resolver(HTTPSignatureKeyResolver):
+    def __init__(self, key: Ed25519PrivateKey):
+        self._key = key
+
+    def resolve_private_key(self, key_id: str) -> Ed25519PrivateKey:
+        return self._key
+
+    def resolve_public_key(self, key_id: str) -> Any:
+        raise NotImplementedError
+
+
+class EgressSigner:
+    """Sign outbound requests as a Web Bot Auth agent.
+
+    Usage::
+
+        signer = EgressSigner(seed=os.environ["AGENT_KEY_SEED"],
+                              signature_agent="https://myagent.example")
+        headers = signer.sign("POST", url, {"content-type": "application/json"})
+        httpx.post(url, json=body, headers=headers)
+
+    Publish ``signer.directory()`` as JSON at
+    ``https://myagent.example/.well-known/http-message-signatures-directory``
+    (or run ``regent-httpsig keygen`` to generate both the seed and the files).
+    """
+
+    def __init__(self, *, seed: str, signature_agent: str, ttl_minutes: int = 5):
+        raw = b64url_decode(seed)
+        if len(raw) != 32:
+            raise ValueError("seed must be 32 bytes (base64url-encoded)")
+        self._key = Ed25519PrivateKey.from_private_bytes(raw)
+        self.signature_agent = signature_agent
+        self._ttl = ttl_minutes
+        self._jwk = {
+            "kty": "OKP",
+            "crv": "Ed25519",
+            "x": b64url(self._key.public_key().public_bytes_raw()),
+        }
+        self.keyid = jwk_thumbprint(self._jwk)
+
+    @property
+    def public_jwk(self) -> dict[str, Any]:
+        return dict(self._jwk)
+
+    def directory(self) -> dict[str, Any]:
+        """The JWKS document to serve at
+        ``/.well-known/http-message-signatures-directory``."""
+        return {
+            "keys": [{**self._jwk, "kid": self.keyid, "use": "sig", "alg": "EdDSA"}]
+        }
+
+    def sign(
+        self,
+        method: str,
+        url: str,
+        headers: dict[str, str] | None = None,
+        *,
+        covered: tuple[str, ...] = _DEFAULT_COVERED,
+        label: str = "sig1",
+    ) -> dict[str, str]:
+        """Return ``headers`` + ``Signature-Agent``/``Signature-Input``/``Signature``."""
+        out = dict(headers or {})
+        out["Signature-Agent"] = f'"{self.signature_agent}"'  # legacy sf-string form
+        message = Message(method.upper(), url, out)
+        signer = HTTPMessageSigner(
+            signature_algorithm=ED25519, key_resolver=_Resolver(self._key)
+        )
+        now = datetime.now()
+        signer.sign(
+            message,
+            key_id=self.keyid,
+            label=label,
+            tag="web-bot-auth",
+            created=now,
+            expires=now + timedelta(minutes=self._ttl),
+            covered_component_ids=covered,
+        )
+        return dict(message.headers)

regent_httpsig/verify.py

@@ -0,0 +1,342 @@
+"""Inbound agent-identity verification — RFC 9421 HTTP Message Signatures.
+
+Two schemes are accepted side by side (both ride the same ``Signature`` /
+``Signature-Input`` headers; the difference is where the public key comes from):
+
+- **Web Bot Auth** (draft-meunier-web-bot-auth-architecture): the agent's
+  operator publishes an Ed25519 JWKS at
+  ``{Signature-Agent}/.well-known/http-message-signatures-directory`` and signs
+  every request with ``tag="web-bot-auth"``. OpenAI's agents sign all their
+  traffic this way today. Both wire forms of ``Signature-Agent`` are accepted:
+  the draft -05 sf-dictionary (covered with ``;key=``) and the legacy bare
+  sf-string OpenAI ships.
+- **AAuth** (draft-hardt-oauth-aauth-protocol, identity-based mode): the agent
+  carries a JWT ``agent_token`` (``typ: aa-agent+jwt``) in the ``Signature-Key``
+  header; the token's issuer JWKS (``{iss}/.well-known/aauth-agent.json`` →
+  ``jwks_uri``) verifies the token, and the token's ``cnf.jwk`` verifies the
+  request signature (proof of possession). Requires the ``[aauth]`` extra.
+
+Directory fetches are SSRF-guarded (https-only, public-IP-only, size-capped,
+no redirects) and cached per verifier instance. A bad or missing signature
+yields ``None`` — verification failure is a result, not an exception.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import timedelta
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from http_message_signatures import HTTPMessageVerifier  # type: ignore[attr-defined]
+
+from regent_httpsig.config import HttpsigConfig
+from regent_httpsig.jwk import jwk_thumbprint, load_ed25519_jwk
+from regent_httpsig.netguard import NotPublicURL, assert_public_url
+from regent_httpsig.sfv import (
+    ED25519,
+    DictKeyComponentResolver,
+    Message,
+    StaticKeyResolver,
+    parse_signature_agent,
+    parse_signature_key_header,
+)
+
+__all__ = ["HttpsigVerifier", "VerifiedSignature", "WBA_TAG"]
+
+logger = logging.getLogger("regent_httpsig")
+
+WBA_TAG = "web-bot-auth"
+WBA_DIRECTORY_PATH = "/.well-known/http-message-signatures-directory"
+AAUTH_METADATA_PATH = "/.well-known/aauth-agent.json"
+AAUTH_JWT_TYP = "aa-agent+jwt"
+
+
+@dataclass
+class VerifiedSignature:
+    """A successfully verified inbound agent signature."""
+
+    scheme: str  # "web-bot-auth" | "aauth"
+    agent: str  # WBA: Signature-Agent origin; AAuth: the token issuer
+    keyid: str  # RFC 7638 / RFC 8037 A.3 JWK thumbprint
+    trusted: bool  # agent/issuer is on the configured trust list
+    sub: str | None = None  # AAuth agent id (token `sub`)
+    label: str = ""
+    claims: dict[str, Any] = field(default_factory=dict)  # AAuth token claims (redacted)
+
+    def context(self) -> dict[str, Any]:
+        """A flat dict suitable for logging / policy engines / audit trails."""
+        out: dict[str, Any] = {
+            "signed_agent": True,
+            "signature_scheme": self.scheme,
+            "signature_agent": self.agent,
+            "signature_keyid": self.keyid,
+            "signature_trusted": self.trusted,
+        }
+        if self.sub:
+            out["signature_sub"] = self.sub
+        return out
+
+
+def _keys_from_jwks(doc: dict[str, Any]) -> dict[str, Ed25519PublicKey]:
+    keys: dict[str, Ed25519PublicKey] = {}
+    for jwk in list(doc.get("keys") or [])[:10]:
+        try:
+            keys[jwk_thumbprint(jwk)] = load_ed25519_jwk(jwk)
+        except Exception:  # noqa: BLE001 — skip non-Ed25519 / malformed keys
+            continue
+    return keys
+
+
+class HttpsigVerifier:
+    """Verify RFC 9421-signed agent requests (Web Bot Auth + AAuth).
+
+    Instances are cheap and hold their own directory cache; create one per
+    application and reuse it. ``http_client`` is optional — pass your app's
+    shared :class:`httpx.AsyncClient` to reuse its pool.
+
+    Usage::
+
+        verifier = HttpsigVerifier()
+        sig = await verifier.verify("POST", "https://api.example/v1/orders", headers)
+        if sig:
+            print(sig.agent)   # e.g. "https://chatgpt.com"
+    """
+
+    def __init__(
+        self,
+        config: HttpsigConfig | None = None,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.config = config or HttpsigConfig()
+        self._http = http_client
+        self._owns_client = http_client is None
+        # url -> (expires_monotonic, parsed JSON | None for negative entries)
+        self._cache: dict[str, tuple[float, dict[str, Any] | None]] = {}
+
+    async def verify(
+        self, method: str, url: str, headers: Mapping[str, str]
+    ) -> VerifiedSignature | None:
+        """Verify the request's agent signature. Returns ``None`` when there is
+        no ``Signature`` header, the signature is invalid, or the signer's keys
+        cannot be (safely) fetched — never raises on untrusted input."""
+        hdrs = {str(k): str(v) for k, v in headers.items()}
+        if not any(k.lower() == "signature" for k in hdrs):
+            return None
+        result: VerifiedSignature | None = None
+        try:
+            if any(k.lower() == "signature-key" for k in hdrs):
+                result = await self._verify_aauth(method, url, hdrs)
+            if result is None:
+                result = await self._verify_web_bot_auth(method, url, hdrs)
+        except Exception as exc:  # noqa: BLE001 — belt and braces
+            logger.warning("httpsig verify error: %s", str(exc)[:200])
+            return None
+        if result is not None:
+            logger.info(
+                "httpsig verified scheme=%s agent=%s keyid=%s trusted=%s",
+                result.scheme, result.agent, result.keyid[:16], result.trusted,
+            )
+        return result
+
+    async def aclose(self) -> None:
+        if self._owns_client and self._http is not None:
+            await self._http.aclose()
+            self._http = None
+
+    # ── directory fetching (SSRF-guarded, cached) ────────────────────────────
+
+    def _cache_get(self, url: str) -> tuple[bool, dict[str, Any] | None]:
+        entry = self._cache.get(url)
+        if entry and entry[0] > time.monotonic():
+            return True, entry[1]
+        return False, None
+
+    def _cache_put(self, url: str, doc: dict[str, Any] | None, ttl: float) -> None:
+        if len(self._cache) >= self.config.cache_max_entries:
+            # Evict the soonest-to-expire entry; bounds memory against keyid spam.
+            self._cache.pop(min(self._cache, key=lambda k: self._cache[k][0]), None)
+        self._cache[url] = (time.monotonic() + ttl, doc)
+
+    async def _fetch_json(self, url: str) -> dict[str, Any] | None:
+        """Fetch an attacker-nameable identity document safely: https-only
+        (except allow-listed dev hosts), public-IP-only, size-capped, cached."""
+        cfg = self.config
+        hit, doc = self._cache_get(url)
+        if hit:
+            return doc
+        try:
+            parsed = urlsplit(url)
+            if parsed.scheme != "https" and parsed.hostname not in cfg.insecure_hosts:
+                raise NotPublicURL("identity directories must be https")
+            await assert_public_url(url, cfg.insecure_hosts)
+            if self._http is None:
+                self._http = httpx.AsyncClient()
+            resp = await self._http.get(
+                url,
+                timeout=cfg.fetch_timeout,
+                follow_redirects=False,
+                headers={"accept": "application/json"},
+            )
+            resp.raise_for_status()
+            if len(resp.content) > cfg.max_directory_bytes:
+                raise ValueError("directory too large")
+            doc = resp.json()
+            if not isinstance(doc, dict):
+                raise ValueError("directory is not a JSON object")
+        except Exception as exc:  # noqa: BLE001 — any failure = unverifiable, not fatal
+            logger.info("directory fetch failed url=%s: %s", url, str(exc)[:200])
+            self._cache_put(url, None, cfg.negative_cache_ttl)
+            return None
+        self._cache_put(url, doc, cfg.cache_ttl)
+        return doc
+
+    # ── Web Bot Auth ─────────────────────────────────────────────────────────
+
+    async def _verify_web_bot_auth(
+        self, method: str, url: str, headers: dict[str, str]
+    ) -> VerifiedSignature | None:
+        message = Message(method, url, headers)
+        agent_header = message.headers.get("signature-agent")
+        if not agent_header:
+            return None  # no directory to verify against — can't establish identity
+        origin = parse_signature_agent(agent_header)
+        if not origin or not origin.startswith(("https://", "http://")):
+            return None
+        directory = await self._fetch_json(origin.rstrip("/") + WBA_DIRECTORY_PATH)
+        if not directory:
+            return None
+        keys = _keys_from_jwks(directory)
+        if not keys:
+            return None
+
+        verifier = HTTPMessageVerifier(
+            signature_algorithm=ED25519,
+            key_resolver=StaticKeyResolver(keys),
+            component_resolver_class=DictKeyComponentResolver,
+        )
+        try:
+            results = await asyncio.to_thread(
+                verifier.verify,
+                message,
+                max_age=timedelta(hours=self.config.max_age_hours),
+                expect_tag=WBA_TAG,
+            )
+        except Exception as exc:  # noqa: BLE001 — invalid signature = unverified
+            logger.info("web-bot-auth invalid agent=%s: %s", origin, str(exc)[:200])
+            return None
+        if not results:
+            return None
+        res = results[0]
+        return VerifiedSignature(
+            scheme=WBA_TAG,
+            agent=origin,
+            keyid=str(res.parameters.get("keyid", "")),
+            trusted=origin in self.config.trusted_agents,
+            label=str(res.label),
+        )
+
+    # ── AAuth (identity-based mode) ──────────────────────────────────────────
+
+    async def _verify_aauth(
+        self, method: str, url: str, headers: dict[str, str]
+    ) -> VerifiedSignature | None:
+        try:
+            import jwt as pyjwt  # the [aauth] extra
+        except ImportError:
+            logger.info("Signature-Key present but pyjwt is not installed "
+                        "(pip install 'regent-httpsig[aauth]')")
+            return None
+
+        message = Message(method, url, headers)
+        parsed = parse_signature_key_header(message.headers.get("signature-key", ""))
+        if not parsed:
+            return None
+        label, token = parsed
+
+        try:
+            header = pyjwt.get_unverified_header(token)
+            unverified = pyjwt.decode(token, options={"verify_signature": False})
+        except Exception:  # noqa: BLE001
+            return None
+        if header.get("typ") != AAUTH_JWT_TYP or header.get("alg") in (None, "none"):
+            return None
+        iss = str(unverified.get("iss", ""))
+        bad_iss = unverified.get("dwk") != "aauth-agent.json" or not iss.startswith("https://")
+        if bad_iss and not (
+            iss and urlsplit(iss).hostname in self.config.insecure_hosts  # dev escape
+        ):
+            return None
+
+        # 1) Verify the agent_token against the issuer's published JWKS.
+        metadata = await self._fetch_json(iss.rstrip("/") + AAUTH_METADATA_PATH)
+        if not metadata or not metadata.get("jwks_uri"):
+            return None
+        jwks = await self._fetch_json(str(metadata["jwks_uri"]))
+        if not jwks:
+            return None
+        issuer_key = None
+        for k in list(jwks.get("keys") or [])[:10]:
+            if k.get("kid") == header.get("kid") or len(jwks.get("keys") or []) == 1:
+                try:
+                    issuer_key = pyjwt.PyJWK(k).key
+                    break
+                except Exception:  # noqa: BLE001
+                    continue
+        if issuer_key is None:
+            return None
+        try:
+            claims = pyjwt.decode(
+                token,
+                key=issuer_key,
+                algorithms=["EdDSA", "ES256", "RS256"],
+                options={"require": ["iss", "sub", "exp", "iat"]},
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.info("aauth token invalid iss=%s: %s", iss, str(exc)[:200])
+            return None
+
+        # 2) Proof of possession: the request signature must verify against cnf.jwk.
+        cnf_jwk = (claims.get("cnf") or {}).get("jwk")
+        if not isinstance(cnf_jwk, dict):
+            return None
+        try:
+            pop_key = load_ed25519_jwk(cnf_jwk)
+        except ValueError:
+            return None
+        verifier = HTTPMessageVerifier(
+            signature_algorithm=ED25519,
+            key_resolver=StaticKeyResolver({}, default=pop_key),
+            component_resolver_class=DictKeyComponentResolver,
+        )
+        try:
+            # No expect_label: upstream requires expect_tag alongside it, and the
+            # AAuth drafts' tag is still moving — we verify all signatures against
+            # the possession key and match the Signature-Key label ourselves.
+            results = await asyncio.to_thread(
+                verifier.verify,
+                message,
+                max_age=timedelta(hours=self.config.max_age_hours),
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.info("aauth PoP invalid iss=%s: %s", iss, str(exc)[:200])
+            return None
+        if not any(str(r.label) == label for r in results):
+            return None
+
+        return VerifiedSignature(
+            scheme="aauth",
+            agent=iss,
+            keyid=jwk_thumbprint(cnf_jwk),
+            trusted=iss in self.config.trusted_agents,
+            sub=str(claims.get("sub", "")),
+            label=label,
+            claims={k: claims[k] for k in ("iss", "sub", "exp", "ps") if k in claims},
+        )

regent_httpsig-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: regent-httpsig
+Version: 0.1.0
+Summary: Verify and sign AI agent HTTP traffic in Python — RFC 9421 HTTP Message Signatures: Web Bot Auth (what OpenAI ships) and AAuth.
+Project-URL: Homepage, https://github.com/regent-protocol/regent-httpsig
+Project-URL: Repository, https://github.com/regent-protocol/regent-httpsig
+Project-URL: Issues, https://github.com/regent-protocol/regent-httpsig/issues
+Author-email: Regent Protocol <info@regentprotocol.org>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: aauth,agent-identity,ai-agents,bot-detection,ed25519,http-message-signatures,rfc9421,web-bot-auth
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
+Requires-Dist: http-message-signatures>=2.0.1
+Requires-Dist: httpx>=0.25
+Requires-Dist: typing-extensions>=4.10
+Provides-Extra: aauth
+Requires-Dist: pyjwt>=2.8.0; extra == 'aauth'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# regent-httpsig
+
+**Verify and sign AI agent HTTP traffic in Python — the way OpenAI signs and Cloudflare verifies.**
+RFC 9421 · Web Bot Auth · AAuth
+
+OpenAI's agents cryptographically sign every HTTP request they make. Cloudflare, AWS WAF and
+Google verify those signatures. This library brings both sides of that handshake to Python:
+**verify** signed agents hitting your API, and **sign** your own agent's traffic so bot walls
+recognize it.
+
+```bash
+pip install regent-httpsig
+```
+
+## Verify: know which AI agent is calling — in 5 lines
+
+```python
+from fastapi import FastAPI
+from regent_httpsig import HttpsigVerifier
+from regent_httpsig.fastapi import attach, SignatureDep, VerifiedSignature
+
+app = FastAPI()
+attach(app, HttpsigVerifier())
+
+@app.post("/v1/orders")
+async def create_order(sig: VerifiedSignature | None = SignatureDep):
+    if sig:
+        print(sig.agent)    # "https://chatgpt.com"
+        print(sig.keyid)    # RFC 7638 key thumbprint
+    ...
+```
+
+No FastAPI? The core has no framework dependencies:
+
+```python
+verifier = HttpsigVerifier()
+sig = await verifier.verify(method, url, headers)   # VerifiedSignature | None
+```
+
+Verification is **enrichment by default**: no `Signature` header costs nothing, a bad
+signature yields `None`, and nothing ever raises on untrusted input. Use
+`regent_httpsig.fastapi.RequiredSignatureDep` when a signature must be present — the 401
+tells the agent exactly how to sign.
+
+## Sign: get your agent past bot walls
+
+```python
+from regent_httpsig import EgressSigner
+
+signer = EgressSigner(seed=os.environ["AGENT_KEY_SEED"],
+                      signature_agent="https://myagent.example")
+headers = signer.sign("POST", url, {"content-type": "application/json"})
+resp = httpx.post(url, json=body, headers=headers)
+```
+
+Generate a key and the ready-to-publish `/.well-known/` files in one command:
+
+```bash
+regent-httpsig keygen --agent https://myagent.example --out ./well-known/
+```
+
+Publish the directory at `https://myagent.example/.well-known/http-message-signatures-directory`
+and every Web Bot Auth verifier on the internet can now identify your agent.
+
+## What exactly is verified
+
+| Check | Status |
+|---|---|
+| RFC 9421 Appendix B.2.6 Ed25519 vector (byte-exact) | ✅ in CI |
+| Web Bot Auth draft -05 A.2.2 — sf-dictionary `Signature-Agent` covered with `;key=` | ✅ in CI¹ |
+| Web Bot Auth A.2.3 — legacy sf-string form (**what OpenAI ships in production**) | ✅ in CI |
+| Sign → verify roundtrip (fresh keys, full pipeline) | ✅ in CI |
+| AAuth identity-mode roundtrip (`aa-agent+jwt` + `cnf.jwk` proof of possession) | ✅ in CI |
+| Tampered request / expired signature / wrong directory key rejected | ✅ in CI |
+
+¹ The signature bytes printed in the draft's own A.2.2 example do **not** verify over the
+draft's own signature base (the legacy A.2.3 vector and RFC 9421 B.2.6 both do, so the defect
+is in the example, not the canonicalization). Ed25519 is deterministic, so our test pins the
+vector re-signed with the same RFC test key over the same byte-exact base — reported upstream.
+
+## Both dialects, one verifier
+
+- **Web Bot Auth** (`draft-meunier-web-bot-auth-architecture`): key discovery via
+  `{Signature-Agent}/.well-known/http-message-signatures-directory`. Both wire forms of
+  `Signature-Agent` are accepted — the current sf-dictionary and the legacy bare sf-string
+  OpenAI actually sends.
+- **AAuth** (`draft-hardt-oauth-aauth-protocol`, identity-based mode): the agent carries a
+  JWT `agent_token` in `Signature-Key`; the issuer's JWKS verifies the token, the token's
+  `cnf.jwk` verifies the request signature. Install with `pip install 'regent-httpsig[aauth]'`.
+  For a full-protocol AAuth implementation (both roles, all token types) see
+  [christian-posta/aauth-python-library](https://github.com/christian-posta/aauth-python-library) —
+  this library is the thin relying-party verifier that handles both dialects.
+
+## Security model (what a naive implementation gets wrong)
+
+The verifier fetches key directories from **attacker-nameable origins** — whoever signs a
+request chooses its `Signature-Agent`. regent-httpsig ships with the guard rails on:
+
+- **SSRF protection by default**: https-only, every resolved IP must be public (catches
+  `169.254.169.254`, loopback, private ranges, DNS names mapping to internal services),
+  redirects never followed, responses size-capped.
+- **Bounded caching**: per-instance TTL cache with eviction — a keyid-spam attack can't
+  grow memory; failures are negative-cached so a dead origin can't be used to slow you down.
+- **A valid signature proves key possession — not trustworthiness.** `VerifiedSignature.trusted`
+  reflects only your configured allow-list; deciding *whether to trust* a key is your policy
+  layer's job.
+
+Known sharp edges of the underlying ecosystem, already handled: the upstream
+`http-message-signatures` library cannot resolve RFC 9421 `;key=` dictionary members (we
+provide the component resolver), it looks up header names case-sensitively while ASGI
+frameworks lowercase them (we wrap), and it forgets to declare `typing_extensions` (we
+declare it).
+
+## Configuration
+
+```python
+from regent_httpsig import HttpsigConfig, HttpsigVerifier
+
+verifier = HttpsigVerifier(HttpsigConfig(
+    trusted_agents=frozenset({"https://chatgpt.com", "https://operator.openai.com"}),
+    max_age_hours=25,       # reject signatures created earlier than this
+    cache_ttl=600,          # key-directory cache seconds
+))
+```
+
+Pass your app's shared client to reuse its pool: `HttpsigVerifier(http_client=my_async_client)`.
+
+## Honest limitations
+
+- Web Bot Auth and AAuth are **IETF drafts** (RFC 9421 itself is a final standard). We track
+  the drafts; breaking draft changes land as minor releases while we're 0.x.
+- **Ed25519 only** for now — it's what the agent ecosystem ships.
+- Body coverage (`content-digest`) is verified when covered by the signature, but this
+  library does not require it; decide per-route whether you need it.
+
+## Related projects
+
+[cloudflare/web-bot-auth](https://github.com/cloudflare/web-bot-auth) (TypeScript/Rust) ·
+[christian-posta/aauth-python-library](https://github.com/christian-posta/aauth-python-library)
+(full AAuth protocol) · [pyauth/http-message-signatures](https://github.com/pyauth/http-message-signatures)
+(the RFC 9421 primitive this builds on)
+
+---
+
+Built and battle-tested in production by [Regent Protocol](https://regentprotocol.org) —
+runtime control and identity for AI agents. Apache-2.0.

regent_httpsig-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+regent_httpsig/__init__.py,sha256=UZ-RmE0KLmqjD7JV7LnSOnPTc5FPO-5OtQzvsYq9PAs,987
+regent_httpsig/cli.py,sha256=WUSLQ2WuEX4E85L2C2EgoUfu5cWpj6MRSG1UVNHpzcw,2005
+regent_httpsig/config.py,sha256=xkILlWugaD8Nn4huAgL6RP-C916KxCYRn0YpqCkMOGc,1422
+regent_httpsig/fastapi.py,sha256=YmfrKdeMft2vpuiRlivIEHYC4BIs3ioR7T3t1ZEzcJ4,3707
+regent_httpsig/jwk.py,sha256=h4vgnIgpnyKeWdWpm7g_hEyXZOPVREWn-bD4JN07tT0,1637
+regent_httpsig/netguard.py,sha256=Sqg08mdC94RWvnQLJaH4weZW0nN2VlTJF5wVF8VYGHY,2121
+regent_httpsig/sfv.py,sha256=kcQsBLw9h4h_6D3z2rv0-3_gLZQYC47B9VZi-oS_Vgk,4975
+regent_httpsig/sign.py,sha256=B5ChxFxuuKL0i10bGrgFImzyh8GMjWIqNDECXehBWTA,4397
+regent_httpsig/verify.py,sha256=YVcYWqxUBmqSdWrW8nBCSceT7YApAUjO5J-FIMKBRVM,14256
+regent_httpsig-0.1.0.dist-info/METADATA,sha256=4v_RgOudkaT3ui9921kZhM8R5fGfJbLl5e3e1pDBTh0,7871
+regent_httpsig-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+regent_httpsig-0.1.0.dist-info/entry_points.txt,sha256=SgZdmc27V14IAmwOjbBoCYLsbrALaqdTUHNHLbil2dU,59
+regent_httpsig-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+regent_httpsig-0.1.0.dist-info/RECORD,,

regent_httpsig-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

regent_httpsig-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+regent-httpsig = regent_httpsig.cli:main

regent_httpsig-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.