regent-httpsig 0.1.1__tar.gz → 0.2.0__tar.gz

{regent_httpsig-0.1.1 → regent_httpsig-0.2.0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.2.0
+
+AAuth draft **-11** support (per the editor's copy, ahead of datatracker publication):
+
+- **Fully-specified algorithms (RFC 9864):** `Ed25519` accepted everywhere
+  (registered with PyJWT, including JWKS entries PyJWK cannot parse).
+  New `HttpsigConfig.require_fully_specified_algs` enforces the -11 MUST NOT on
+  the polymorphic `EdDSA`; the default keeps accepting it while the -10
+  ecosystem migrates, and will flip when -11 posts.
+- **Person tokens** (`typ: aa-person+jwt`): PS-issued, per-resource `aud`,
+  `cnf`-bound, ≤1h lifetime — verified via `{iss}/.well-known/aauth-person.json`.
+  Opt-in: set `HttpsigConfig.resource_url` (the token's `aud` must name it).
+  Result scheme: `"aauth-person"`, `sub` = the PS's directed user identifier.
+- Strict mode also enforces the -11 requirement that `cnf.jwk` carries a
+  fully-specified `alg` member.
+
 ## 0.1.1
 
 - AAuth: tolerate absent `keyid` (RFC 9421 makes it optional; the key comes from

{regent_httpsig-0.1.1 → regent_httpsig-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: regent-httpsig
-Version: 0.1.1
+Version: 0.2.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
@@ -72,6 +72,12 @@ 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.
 
+> **Behind a reverse proxy?** The agent signed the *public* URL
+> (`https://api.example/…`), but your ASGI server sees `http://container/…`. The FastAPI
+> dependency rebuilds the signed URL from `X-Forwarded-Proto` + `Host`, so make sure your
+> proxy forwards the scheme — nginx: `proxy_set_header X-Forwarded-Proto $scheme;`.
+> If signatures mysteriously fail to verify in production, check this first.
+
 ## Sign: get your agent past bot walls
 
 ```python
@@ -125,6 +131,9 @@ keyid-less shape is pinned in CI.
 - **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]'`.
+  Tracks the **-11 editor's copy**: fully-specified algorithms (RFC 9864, `Ed25519` — with a
+  transition flag for the -10 ecosystem's `EdDSA`) and **person tokens** (`aa-person+jwt`,
+  opt-in via `HttpsigConfig.resource_url`).
   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.

{regent_httpsig-0.1.1 → regent_httpsig-0.2.0}/README.md

@@ -42,6 +42,12 @@ 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.
 
+> **Behind a reverse proxy?** The agent signed the *public* URL
+> (`https://api.example/…`), but your ASGI server sees `http://container/…`. The FastAPI
+> dependency rebuilds the signed URL from `X-Forwarded-Proto` + `Host`, so make sure your
+> proxy forwards the scheme — nginx: `proxy_set_header X-Forwarded-Proto $scheme;`.
+> If signatures mysteriously fail to verify in production, check this first.
+
 ## Sign: get your agent past bot walls
 
 ```python
@@ -95,6 +101,9 @@ keyid-less shape is pinned in CI.
 - **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]'`.
+  Tracks the **-11 editor's copy**: fully-specified algorithms (RFC 9864, `Ed25519` — with a
+  transition flag for the -10 ecosystem's `EdDSA`) and **person tokens** (`aa-person+jwt`,
+  opt-in via `HttpsigConfig.resource_url`).
   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.

{regent_httpsig-0.1.1 → regent_httpsig-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "regent-httpsig"
-version = "0.1.1"
+version = "0.2.0"
 description = "Verify and sign AI agent HTTP traffic in Python — RFC 9421 HTTP Message Signatures: Web Bot Auth (what OpenAI ships) and AAuth."
 readme = "README.md"
 license = "Apache-2.0"

{regent_httpsig-0.1.1 → regent_httpsig-0.2.0}/src/regent_httpsig/__init__.py

@@ -11,7 +11,7 @@ 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.1"
+__version__ = "0.2.0"
 
 __all__ = [
     "DIRECTORY_MEDIA_TYPE",

{regent_httpsig-0.1.1 → regent_httpsig-0.2.0}/src/regent_httpsig/config.py

@@ -30,3 +30,11 @@ class HttpsigConfig:
     # 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)
+    # AAuth -11 (editor's copy): JOSE algs must be fully-specified per RFC 9864 —
+    # implementations MUST NOT accept the polymorphic "EdDSA". True enforces that;
+    # the False default keeps accepting "EdDSA" while the -10 ecosystem migrates.
+    require_fully_specified_algs: bool = False
+    # This service's public URL (e.g. "https://api.example"). Required to accept
+    # AAuth person tokens — their `aud` must name this resource. None disables
+    # the person-token path entirely.
+    resource_url: str | None = None

{regent_httpsig-0.1.1 → regent_httpsig-0.2.0}/src/regent_httpsig/verify.py

@@ -55,7 +55,23 @@ 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_PERSON_METADATA_PATH = "/.well-known/aauth-person.json"
 AAUTH_JWT_TYP = "aa-agent+jwt"
+AAUTH_PERSON_TYP = "aa-person+jwt"
+# -11: a person token "lives at most one hour" — enforced with a small tolerance.
+PERSON_TOKEN_MAX_LIFETIME = 3600 + 90
+
+
+def _register_fully_specified_algs() -> None:
+    """Register 'Ed25519' (RFC 9864 fully-specified) with PyJWT — same math as
+    the polymorphic 'EdDSA', which AAuth -11 forbids implementations to accept."""
+    import contextlib
+
+    import jwt as pyjwt
+    from jwt.algorithms import OKPAlgorithm
+
+    with contextlib.suppress(ValueError):  # already registered = fine
+        pyjwt.register_algorithm("Ed25519", OKPAlgorithm())
 
 
 @dataclass
@@ -286,22 +302,47 @@ class HttpsigVerifier:
             return None
         label, token = parsed
 
+        _register_fully_specified_algs()
         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"):
+        if header.get("alg") in (None, "none"):
+            return None
+
+        # -11 token-type dispatch: agent tokens (identity mode) and person tokens
+        # (PS-issued, per-resource, opt-in via config.resource_url).
+        typ = header.get("typ")
+        if typ == AAUTH_JWT_TYP:
+            scheme, expected_dwk = "aauth", "aauth-agent.json"
+            metadata_path, audience = AAUTH_METADATA_PATH, None
+        elif typ == AAUTH_PERSON_TYP:
+            if not self.config.resource_url:
+                logger.info("person token presented but config.resource_url is not "
+                            "set — person-token verification is disabled")
+                return None
+            scheme, expected_dwk = "aauth-person", "aauth-person.json"
+            metadata_path, audience = AAUTH_PERSON_METADATA_PATH, self.config.resource_url
+        else:
             return None
+
         iss = str(unverified.get("iss", ""))
-        bad_iss = unverified.get("dwk") != "aauth-agent.json" or not iss.startswith("https://")
+        bad_iss = unverified.get("dwk") != expected_dwk 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)
+        # AAuth -11 / RFC 9864: fully-specified algorithms. "EdDSA" (polymorphic)
+        # is accepted only while require_fully_specified_algs is False — a
+        # transition affordance for the -10 ecosystem.
+        allowed_algs = ["Ed25519", "ES256", "RS256"]
+        if not self.config.require_fully_specified_algs:
+            allowed_algs.append("EdDSA")
+
+        # 1) Verify the token against the issuer's published JWKS.
+        metadata = await self._fetch_json(iss.rstrip("/") + metadata_path)
         if not metadata or not metadata.get("jwks_uri"):
             return None
         jwks = await self._fetch_json(str(metadata["jwks_uri"]))
@@ -314,24 +355,46 @@ class HttpsigVerifier:
                     issuer_key = pyjwt.PyJWK(k).key
                     break
                 except Exception:  # noqa: BLE001
-                    continue
+                    # PyJWK's internal registry predates RFC 9864 names — a JWKS
+                    # advertising alg "Ed25519" is valid in -11 but unknown to it.
+                    try:
+                        issuer_key = load_ed25519_jwk(k)
+                        break
+                    except ValueError:
+                        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"]},
+                algorithms=allowed_algs,
+                audience=audience,
+                options={
+                    "require": ["iss", "sub", "exp", "iat"],
+                    "verify_aud": audience is not None,
+                },
             )
         except Exception as exc:  # noqa: BLE001
             logger.info("aauth token invalid iss=%s: %s", iss, str(exc)[:200])
             return None
 
+        # -11: a person token "lives at most one hour".
+        if typ == AAUTH_PERSON_TYP:
+            lifetime = int(claims.get("exp", 0)) - int(claims.get("iat", 0))
+            if lifetime <= 0 or lifetime > PERSON_TOKEN_MAX_LIFETIME:
+                logger.info("person token lifetime %ss out of bounds iss=%s", lifetime, iss)
+                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
+        # -11 strict mode: the cnf JWK "MUST carry a fully-specified alg member".
+        if self.config.require_fully_specified_algs and cnf_jwk.get("alg") != "Ed25519":
+            logger.info("cnf.jwk alg %r is not fully-specified iss=%s",
+                        cnf_jwk.get("alg"), iss)
+            return None
         try:
             pop_key = load_ed25519_jwk(cnf_jwk)
         except ValueError:
@@ -357,11 +420,15 @@ class HttpsigVerifier:
             return None
 
         return VerifiedSignature(
-            scheme="aauth",
+            scheme=scheme,
             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},
+            claims={
+                k: claims[k]
+                for k in ("iss", "sub", "exp", "ps", "aud", "jti", "mission_s256")
+                if k in claims
+            },
         )

{regent_httpsig-0.1.1 → regent_httpsig-0.2.0}/tests/test_verifier.py

@@ -197,6 +197,115 @@ async def test_aauth_without_keyid_param(monkeypatch: pytest.MonkeyPatch) -> Non
     assert sig is not None and sig.scheme == "aauth" and sig.sub == "agent-42"
 
 
+def _issuer_pair(kid: str = "iss-1", alg: str = "EdDSA"):
+    priv = Ed25519PrivateKey.generate()
+    jwk = {"kty": "OKP", "crv": "Ed25519", "kid": kid, "alg": alg,
+           "x": b64url(priv.public_key().public_bytes_raw())}
+    return priv, jwk
+
+
+def _mint(issuer_priv, *, typ: str, alg: str, claims: dict) -> str:
+    from regent_httpsig.verify import _register_fully_specified_algs
+
+    _register_fully_specified_algs()
+    return pyjwt.encode(claims, issuer_priv, algorithm=alg,
+                        headers={"typ": typ, "kid": "iss-1"})
+
+
+class TestFullySpecifiedAlgs:
+    """AAuth -11 / RFC 9864: Ed25519 accepted; polymorphic EdDSA gated by config."""
+
+    async def _roundtrip(self, alg: str, config: HttpsigConfig,
+                         monkeypatch: pytest.MonkeyPatch):
+        issuer_priv, issuer_jwk = _issuer_pair(alg=alg)
+        agent = EgressSigner(seed=generate_seed(), signature_agent="https://issuer.example")
+        now = int(time.time())
+        token = _mint(issuer_priv, typ="aa-agent+jwt", alg=alg, claims={
+            "iss": "https://issuer.example", "sub": "a-1", "iat": now, "exp": now + 600,
+            "dwk": "aauth-agent.json",
+            "cnf": {"jwk": {**agent.public_jwk, "alg": "Ed25519"}},
+        })
+        url = "https://api.example/v1/x"
+        headers = agent.sign("POST", url, {"Host": "api.example"})
+        headers["Signature-Key"] = f'sig1=jwt;jwt="{token}"'
+        verifier = HttpsigVerifier(config)
+        monkeypatch.setattr(verifier, "_fetch_json", _mock_fetch({
+            "https://issuer.example/.well-known/aauth-agent.json":
+                {"jwks_uri": "https://issuer.example/j"},
+            "https://issuer.example/j": {"keys": [issuer_jwk]},
+        }))
+        return await verifier.verify("POST", url, headers)
+
+    async def test_ed25519_fully_specified_verifies(self, monkeypatch) -> None:
+        sig = await self._roundtrip("Ed25519", HttpsigConfig(), monkeypatch)
+        assert sig is not None and sig.scheme == "aauth"
+
+    async def test_eddsa_accepted_in_transition_mode(self, monkeypatch) -> None:
+        sig = await self._roundtrip("EdDSA", HttpsigConfig(), monkeypatch)
+        assert sig is not None  # default: -10 ecosystem still accepted
+
+    async def test_eddsa_rejected_in_strict_mode(self, monkeypatch) -> None:
+        strict = HttpsigConfig(require_fully_specified_algs=True)
+        assert await self._roundtrip("EdDSA", strict, monkeypatch) is None
+
+    async def test_ed25519_verifies_in_strict_mode(self, monkeypatch) -> None:
+        strict = HttpsigConfig(require_fully_specified_algs=True)
+        sig = await self._roundtrip("Ed25519", strict, monkeypatch)
+        assert sig is not None
+
+
+class TestPersonTokens:
+    """AAuth -11 person tokens: PS-issued, per-resource aud, cnf-bound, ≤1h."""
+
+    def _headers(self, *, aud: str, lifetime: int = 600):
+        ps_priv, ps_jwk = _issuer_pair()
+        agent = EgressSigner(seed=generate_seed(), signature_agent="https://ps.example")
+        now = int(time.time())
+        token = _mint(ps_priv, typ="aa-person+jwt", alg="Ed25519", claims={
+            "iss": "https://ps.example", "sub": "directed-sub-1", "aud": aud,
+            "iat": now, "exp": now + lifetime, "dwk": "aauth-person.json",
+            "jti": "pt-1", "cnf": {"jwk": {**agent.public_jwk, "alg": "Ed25519"}},
+        })
+        url = "https://api.example/v1/x"
+        headers = agent.sign("POST", url, {"Host": "api.example"})
+        headers["Signature-Key"] = f'sig1=jwt;jwt="{token}"'
+        return url, headers, ps_jwk
+
+    def _verifier(self, ps_jwk, monkeypatch, **cfg):
+        verifier = HttpsigVerifier(HttpsigConfig(**cfg))
+        monkeypatch.setattr(verifier, "_fetch_json", _mock_fetch({
+            "https://ps.example/.well-known/aauth-person.json":
+                {"jwks_uri": "https://ps.example/j"},
+            "https://ps.example/j": {"keys": [ps_jwk]},
+        }))
+        return verifier
+
+    async def test_person_token_roundtrip(self, monkeypatch) -> None:
+        url, headers, ps_jwk = self._headers(aud="https://api.example")
+        v = self._verifier(ps_jwk, monkeypatch, resource_url="https://api.example")
+        sig = await v.verify("POST", url, headers)
+        assert sig is not None
+        assert sig.scheme == "aauth-person"
+        assert sig.agent == "https://ps.example"  # the PS, not the agent operator
+        assert sig.sub == "directed-sub-1"
+        assert sig.claims.get("jti") == "pt-1"
+
+    async def test_person_token_wrong_audience_rejected(self, monkeypatch) -> None:
+        url, headers, ps_jwk = self._headers(aud="https://OTHER.example")
+        v = self._verifier(ps_jwk, monkeypatch, resource_url="https://api.example")
+        assert await v.verify("POST", url, headers) is None
+
+    async def test_person_token_disabled_without_resource_url(self, monkeypatch) -> None:
+        url, headers, ps_jwk = self._headers(aud="https://api.example")
+        v = self._verifier(ps_jwk, monkeypatch)  # no resource_url → path disabled
+        assert await v.verify("POST", url, headers) is None
+
+    async def test_person_token_overlong_lifetime_rejected(self, monkeypatch) -> None:
+        url, headers, ps_jwk = self._headers(aud="https://api.example", lifetime=7200)
+        v = self._verifier(ps_jwk, monkeypatch, resource_url="https://api.example")
+        assert await v.verify("POST", url, headers) is None
+
+
 async def test_cache_is_per_instance() -> None:
     a, b = HttpsigVerifier(), HttpsigVerifier()
     a._cache_put("https://x.example/doc", {"keys": []}, ttl=60)