auth-md 0.1.0__tar.gz

auth_md-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Whosent
+
+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.

auth_md-0.1.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: auth-md
+Version: 0.1.0
+Summary: Minimal helpers for the auth.md agent-registration protocol: discovery metadata, auth.md generation, and ID-JAG verification.
+License: MIT
+Keywords: auth.md,auth-md,agent-auth,ai-agents,id-jag,oauth,agent-registration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyjwt[crypto]>=2.6
+Dynamic: license-file
+
+# auth-md
+
+_Community implementation, not affiliated with WorkOS._
+
+Minimal helpers for the [auth.md](https://github.com/workos/auth.md) agent-registration protocol.
+
+> Early release (0.1.0). Tracks the workos/auth.md agent-services guide as of October 2026. The spec is still evolving.
+
+```sh
+pip install auth-md
+```
+
+Includes `protected_resource_metadata`, `authorization_server_metadata`, `www_authenticate`, `generate_auth_md`, and `verify_id_jag` (trust list, audience, `typ`, asymmetric algorithms only, `client_id`, verified email or phone, `auth_time` freshness, `jti` replay protection).
+
+```python
+from auth_md import verify_id_jag, MemoryJtiStore
+
+identity = verify_id_jag(
+    assertion,
+    audience="https://auth.yourapp.com",
+    trusted_issuers={"https://provider.example": {"display_name": "Provider"}},
+    jti_store=MemoryJtiStore(),  # use Redis or a DB table in production
+)
+```
+
+Never bind a verified ID-JAG to an existing account by email alone; the spec requires a first-link step-up.
+
+MIT licensed.

auth_md-0.1.0/README.md

@@ -0,0 +1,28 @@
+# auth-md
+
+_Community implementation, not affiliated with WorkOS._
+
+Minimal helpers for the [auth.md](https://github.com/workos/auth.md) agent-registration protocol.
+
+> Early release (0.1.0). Tracks the workos/auth.md agent-services guide as of October 2026. The spec is still evolving.
+
+```sh
+pip install auth-md
+```
+
+Includes `protected_resource_metadata`, `authorization_server_metadata`, `www_authenticate`, `generate_auth_md`, and `verify_id_jag` (trust list, audience, `typ`, asymmetric algorithms only, `client_id`, verified email or phone, `auth_time` freshness, `jti` replay protection).
+
+```python
+from auth_md import verify_id_jag, MemoryJtiStore
+
+identity = verify_id_jag(
+    assertion,
+    audience="https://auth.yourapp.com",
+    trusted_issuers={"https://provider.example": {"display_name": "Provider"}},
+    jti_store=MemoryJtiStore(),  # use Redis or a DB table in production
+)
+```
+
+Never bind a verified ID-JAG to an existing account by email alone; the spec requires a first-link step-up.
+
+MIT licensed.

auth_md-0.1.0/auth_md/__init__.py

@@ -0,0 +1,191 @@
+"""auth-md: minimal helpers for the auth.md agent-registration protocol.
+
+Community implementation, not affiliated with WorkOS. Tracks the workos/auth.md
+agent-services guide as of October 2026; the spec is still evolving.
+"""
+
+import time
+
+import jwt
+from jwt import PyJWKClient, PyJWKSet
+
+__all__ = ["protected_resource_metadata", "authorization_server_metadata", "www_authenticate",
+           "generate_auth_md", "verify_id_jag", "MemoryJtiStore", "AgentAuthError"]
+__version__ = "0.1.0"
+
+ID_JAG_TYP = "oauth-id-jag+jwt"
+ID_JAG_ASSERTION_TYPE = "urn:ietf:params:oauth:token-type:id-jag"
+CLAIM_GRANT_TYPE = "urn:workos:agent-auth:grant-type:claim"
+JWT_BEARER_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:jwt-bearer"
+ASSERTION_REVOKED_EVENT = "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"
+# Asymmetric algorithms only. Never accept "none" or HMAC for third-party assertions.
+ALLOWED_ALGS = ["RS256", "PS256", "ES256", "EdDSA"]
+
+
+class AgentAuthError(Exception):
+    """Carries a spec error code (invalid_issuer, replay_detected, login_required, ...)."""
+
+    def __init__(self, code, message, status=400):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+def protected_resource_metadata(*, resource, authorization_servers, scopes_supported=(), resource_name=None):
+    """Protected Resource Metadata (RFC 9728) for /.well-known/oauth-protected-resource."""
+    if not resource or not authorization_servers:
+        raise ValueError("resource and authorization_servers are required")
+    doc = {"resource": resource, "authorization_servers": list(authorization_servers),
+           "scopes_supported": list(scopes_supported), "bearer_methods_supported": ["header"]}
+    if resource_name:
+        doc["resource_name"] = resource_name
+    return doc
+
+
+def authorization_server_metadata(*, issuer, token_endpoint, auth_md_url, identity_endpoint,
+                                  revocation_endpoint=None, claim_endpoint=None, events_endpoint=None,
+                                  identity_types=("identity_assertion", "service_auth"), scopes_supported=()):
+    """Authorization Server metadata (RFC 8414) with the agent_auth block,
+    for /.well-known/oauth-authorization-server."""
+    for name, value in {"issuer": issuer, "token_endpoint": token_endpoint,
+                        "auth_md_url": auth_md_url, "identity_endpoint": identity_endpoint}.items():
+        if not value:
+            raise ValueError(f"missing {name}")
+    claim_flows = "service_auth" in identity_types or "anonymous" in identity_types
+    agent_auth = {"skill": auth_md_url, "identity_endpoint": identity_endpoint,
+                  "identity_types_supported": list(identity_types)}
+    if claim_endpoint:
+        agent_auth["claim_endpoint"] = claim_endpoint
+    if events_endpoint:
+        agent_auth["events_endpoint"] = events_endpoint
+        agent_auth["events_supported"] = [ASSERTION_REVOKED_EVENT]
+    if "identity_assertion" in identity_types:
+        agent_auth["identity_assertion"] = {"assertion_types_supported": [ID_JAG_ASSERTION_TYPE]}
+    doc = {"issuer": issuer, "token_endpoint": token_endpoint, "scopes_supported": list(scopes_supported),
+           "grant_types_supported": [JWT_BEARER_GRANT_TYPE] + ([CLAIM_GRANT_TYPE] if claim_flows else []),
+           "agent_auth": agent_auth}
+    if revocation_endpoint:
+        doc["revocation_endpoint"] = revocation_endpoint
+    return doc
+
+
+def www_authenticate(resource_metadata_url):
+    """WWW-Authenticate value for 401s so agents can discover your metadata."""
+    return f'Bearer resource_metadata="{resource_metadata_url}"'
+
+
+def generate_auth_md(*, service_name, resource_metadata_url, identity_endpoint, token_endpoint,
+                     identity_types=("identity_assertion", "service_auth"), scopes=()):
+    """Generate a minimal, LLM-readable auth.md pointing agents at your discovery documents."""
+    if not all([service_name, resource_metadata_url, identity_endpoint, token_endpoint]):
+        raise ValueError("service_name, resource_metadata_url, identity_endpoint and token_endpoint are required")
+    lines = ["# auth.md", "", f"Instructions for AI agents registering with {service_name} on behalf of a user.", "",
+             "## 1. Discover", "",
+             f"Fetch `{resource_metadata_url}`, then the authorization server metadata it points to. "
+             "The `agent_auth` block lists the endpoints below.", "",
+             "## 2. Register", "", f"POST JSON to `{identity_endpoint}` with one of these `type` values:", ""]
+    if "identity_assertion" in identity_types:
+        lines.append(f'- `identity_assertion`: send `assertion_type: "{ID_JAG_ASSERTION_TYPE}"` and an ID-JAG '
+                     "from your provider minted for this service.")
+    if "service_auth" in identity_types:
+        lines.append("- `service_auth`: send `login_hint` with the user's email. Show the user the returned "
+                     "`user_code` and `verification_uri`.")
+    if "anonymous" in identity_types:
+        lines.append("- `anonymous`: no identity needed. You get limited scopes until a human claims the registration.")
+    lines += ["", "## 3. Get an access token", "",
+              f"Exchange the returned `identity_assertion` at `{token_endpoint}` with `grant_type={JWT_BEARER_GRANT_TYPE}`. "
+              f"During a claim ceremony, poll the same endpoint with `grant_type={CLAIM_GRANT_TYPE}` and your "
+              "`claim_token`, honoring `interval`.", "", "## 4. Scopes", ""]
+    lines += [f"- `{s}`" for s in scopes] or ["- Default scopes only."]
+    lines += ["", "## 5. Errors", "",
+              "- `authorization_pending`: keep polling. `slow_down`: poll less often. `expired_token`: start a new claim.",
+              "- `login_required`: refresh the user's login at your provider and mint a fresh ID-JAG.",
+              "- On a 401 from a previously working token, re-exchange your identity_assertion or restart registration.", ""]
+    return "\n".join(lines)
+
+
+class MemoryJtiStore:
+    """In-memory jti store for development. Use Redis or a database table in production."""
+
+    def __init__(self):
+        self._seen = {}
+
+    def seen(self, jti):
+        now = time.time()
+        self._seen = {k: v for k, v in self._seen.items() if v > now}
+        return jti in self._seen
+
+    def remember(self, jti, ttl_seconds):
+        self._seen[jti] = time.time() + ttl_seconds
+
+
+def verify_id_jag(token, *, trusted_issuers, audience, jti_store, is_known_client_id=None,
+                  max_auth_age_seconds=3600, clock_skew_seconds=60):
+    """Verify an ID-JAG from a trusted agent provider, per the auth.md agent-services guide.
+
+    trusted_issuers: {issuer: {"jwks_uri": ...} or {"jwks": {...}}, optional "display_name"}
+        (jwks_uri defaults to {iss}/.well-known/jwks.json)
+    audience: your authorization server's issuer.
+    jti_store: object with seen(jti) and remember(jti, ttl_seconds). Required for replay protection.
+
+    Raises AgentAuthError with spec error codes. Does not do user matching or first-link step-up;
+    never silently bind an ID-JAG to an existing account by email.
+    """
+    if not trusted_issuers or not audience or jti_store is None:
+        raise ValueError("trusted_issuers, audience and jti_store are required")
+    try:
+        header = jwt.get_unverified_header(token)
+        unverified = jwt.decode(token, options={"verify_signature": False})
+    except jwt.PyJWTError as e:
+        raise AgentAuthError("invalid_signature", f"malformed token: {e}") from e
+    if header.get("typ") != ID_JAG_TYP or header.get("alg") not in ALLOWED_ALGS:
+        raise AgentAuthError("invalid_signature", "wrong typ or disallowed algorithm")
+
+    iss = unverified.get("iss")
+    entry = trusted_issuers.get(iss) if isinstance(iss, str) else None
+    if not entry:
+        raise AgentAuthError("invalid_issuer", "issuer is not on the trust list")
+
+    try:
+        if "jwks" in entry:
+            kid = header.get("kid")
+            keys = [k for k in PyJWKSet.from_dict(entry["jwks"]).keys if kid is None or k.key_id == kid]
+            if not keys:
+                raise AgentAuthError("invalid_signature", "no matching key")
+            key = keys[0].key
+        else:
+            uri = entry.get("jwks_uri") or iss.rstrip("/") + "/.well-known/jwks.json"
+            key = PyJWKClient(uri).get_signing_key_from_jwt(token).key
+        claims = jwt.decode(token, key, algorithms=ALLOWED_ALGS, audience=audience, issuer=iss,
+                            leeway=clock_skew_seconds,
+                            options={"require": ["iss", "sub", "aud", "client_id", "jti", "iat", "exp"]})
+    except jwt.ExpiredSignatureError as e:
+        raise AgentAuthError("expired", "assertion expired") from e
+    except jwt.InvalidAudienceError as e:
+        raise AgentAuthError("invalid_audience", "wrong audience") from e
+    except jwt.MissingRequiredClaimError as e:
+        code = "invalid_client_id" if e.claim == "client_id" else "invalid_signature"
+        raise AgentAuthError(code, str(e)) from e
+    except jwt.PyJWTError as e:
+        raise AgentAuthError("invalid_signature", str(e)) from e
+
+    if is_known_client_id and not is_known_client_id(claims["client_id"], iss):
+        raise AgentAuthError("invalid_client_id", "client_id does not resolve to this provider")
+    if claims.get("email_verified") is not True and claims.get("phone_number_verified") is not True:
+        raise AgentAuthError("missing_verified_email", "no verified email or phone")
+    auth_time = claims.get("auth_time")
+    if not isinstance(auth_time, (int, float)):
+        raise AgentAuthError("login_required", "auth_time missing", 401)
+    if time.time() - auth_time > max_auth_age_seconds:
+        raise AgentAuthError("login_required", "auth_time too old", 401)
+
+    replay_key = f"{iss}|{claims['jti']}"
+    if jti_store.seen(replay_key):
+        raise AgentAuthError("replay_detected", "jti already used")
+    jti_store.remember(replay_key, max(claims["exp"] - claims["iat"], 0) + clock_skew_seconds)
+
+    return {"issuer": claims["iss"], "subject": claims["sub"], "client_id": claims["client_id"],
+            "email": claims.get("email"), "email_verified": claims.get("email_verified") is True,
+            "phone_number": claims.get("phone_number"),
+            "phone_number_verified": claims.get("phone_number_verified") is True,
+            "auth_time": auth_time, "display_name": entry.get("display_name"), "claims": claims}

auth_md-0.1.0/auth_md.egg-info/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: auth-md
+Version: 0.1.0
+Summary: Minimal helpers for the auth.md agent-registration protocol: discovery metadata, auth.md generation, and ID-JAG verification.
+License: MIT
+Keywords: auth.md,auth-md,agent-auth,ai-agents,id-jag,oauth,agent-registration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyjwt[crypto]>=2.6
+Dynamic: license-file
+
+# auth-md
+
+_Community implementation, not affiliated with WorkOS._
+
+Minimal helpers for the [auth.md](https://github.com/workos/auth.md) agent-registration protocol.
+
+> Early release (0.1.0). Tracks the workos/auth.md agent-services guide as of October 2026. The spec is still evolving.
+
+```sh
+pip install auth-md
+```
+
+Includes `protected_resource_metadata`, `authorization_server_metadata`, `www_authenticate`, `generate_auth_md`, and `verify_id_jag` (trust list, audience, `typ`, asymmetric algorithms only, `client_id`, verified email or phone, `auth_time` freshness, `jti` replay protection).
+
+```python
+from auth_md import verify_id_jag, MemoryJtiStore
+
+identity = verify_id_jag(
+    assertion,
+    audience="https://auth.yourapp.com",
+    trusted_issuers={"https://provider.example": {"display_name": "Provider"}},
+    jti_store=MemoryJtiStore(),  # use Redis or a DB table in production
+)
+```
+
+Never bind a verified ID-JAG to an existing account by email alone; the spec requires a first-link step-up.
+
+MIT licensed.

auth_md-0.1.0/auth_md.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+auth_md/__init__.py
+auth_md.egg-info/PKG-INFO
+auth_md.egg-info/SOURCES.txt
+auth_md.egg-info/dependency_links.txt
+auth_md.egg-info/requires.txt
+auth_md.egg-info/top_level.txt
+tests/test_basic.py

auth_md-0.1.0/auth_md.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

auth_md-0.1.0/auth_md.egg-info/requires.txt

@@ -0,0 +1 @@
+pyjwt[crypto]>=2.6

auth_md-0.1.0/auth_md.egg-info/top_level.txt

@@ -0,0 +1 @@
+auth_md

auth_md-0.1.0/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "auth-md"
+version = "0.1.0"
+description = "Minimal helpers for the auth.md agent-registration protocol: discovery metadata, auth.md generation, and ID-JAG verification."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = ["pyjwt[crypto]>=2.6"]
+keywords = ["auth.md", "auth-md", "agent-auth", "ai-agents", "id-jag", "oauth", "agent-registration"]

auth_md-0.1.0/setup.cfg

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

auth_md-0.1.0/tests/test_basic.py

@@ -0,0 +1,78 @@
+import base64, json, time, uuid
+import jwt, pytest
+from cryptography.hazmat.primitives.asymmetric import ec
+from jwt.algorithms import ECAlgorithm
+from auth_md import (verify_id_jag, MemoryJtiStore, AgentAuthError, generate_auth_md,
+                     protected_resource_metadata, authorization_server_metadata)
+
+ISS, AUD = "https://provider.example", "https://auth.service.example"
+priv = ec.generate_private_key(ec.SECP256R1())
+jwk = json.loads(ECAlgorithm.to_jwk(priv.public_key())); jwk.update(kid="k1", alg="ES256")
+TRUST = {ISS: {"jwks": {"keys": [jwk]}}}
+
+def good(**over):
+    c = {"iss": ISS, "sub": "u1", "aud": AUD, "client_id": "agent-app", "jti": str(uuid.uuid4()),
+         "email": "a@b.c", "email_verified": True, "auth_time": int(time.time()) - 60}
+    c.update(over)
+    return {k: v for k, v in c.items() if v is not None}
+
+def sign(claims, typ="oauth-id-jag+jwt"):
+    now = int(time.time())
+    return jwt.encode({"iat": now, "exp": now + 300, **claims}, priv, algorithm="ES256", headers={"kid": "k1", "typ": typ})
+
+def opts():
+    return dict(trusted_issuers=TRUST, audience=AUD, jti_store=MemoryJtiStore())
+
+def test_valid():
+    r = verify_id_jag(sign(good()), **opts())
+    assert r["subject"] == "u1" and r["client_id"] == "agent-app"
+
+def test_phone_instead_of_email():
+    assert verify_id_jag(sign(good(email_verified=False, phone_number_verified=True)), **opts())["phone_number_verified"]
+
+@pytest.mark.parametrize("over,code", [
+    (dict(iss="https://evil.example"), "invalid_issuer"),
+    (dict(aud="https://other.example"), "invalid_audience"),
+    (dict(email_verified=False), "missing_verified_email"),
+    (dict(auth_time=None), "login_required"),
+    (dict(auth_time=int(time.time()) - 7200), "login_required"),
+    (dict(client_id=None), "invalid_client_id"),
+])
+def test_rejects(over, code):
+    with pytest.raises(AgentAuthError) as e:
+        verify_id_jag(sign(good(**over)), **opts())
+    assert e.value.code == code
+
+def test_wrong_typ():
+    with pytest.raises(AgentAuthError):
+        verify_id_jag(sign(good(), typ="JWT"), **opts())
+
+def test_replay():
+    o, t = opts(), sign(good())
+    verify_id_jag(t, **o)
+    with pytest.raises(AgentAuthError) as e:
+        verify_id_jag(t, **o)
+    assert e.value.code == "replay_detected"
+
+def test_alg_none():
+    b = lambda o: base64.urlsafe_b64encode(json.dumps(o).encode()).rstrip(b"=").decode()
+    now = int(time.time())
+    t = f'{b({"alg": "none", "typ": "oauth-id-jag+jwt"})}.{b({**good(), "iat": now, "exp": now + 300})}.'
+    with pytest.raises(AgentAuthError):
+        verify_id_jag(t, **opts())
+
+def test_metadata_and_auth_md():
+    prm = protected_resource_metadata(resource="https://api.acme.dev/", authorization_servers=["https://auth.acme.dev/"])
+    assert "agent_auth" not in prm
+    asm = authorization_server_metadata(issuer="https://auth.acme.dev", token_endpoint="https://auth.acme.dev/oauth2/token",
+                                        auth_md_url="https://acme.dev/auth.md", identity_endpoint="https://auth.acme.dev/agent/identity")
+    assert asm["agent_auth"]["identity_types_supported"] == ["identity_assertion", "service_auth"]
+    md = generate_auth_md(service_name="Acme", resource_metadata_url="https://api.acme.dev/.well-known/oauth-protected-resource",
+                          identity_endpoint="https://auth.acme.dev/agent/identity", token_endpoint="https://auth.acme.dev/oauth2/token")
+    assert "service_auth" in md and "user_claimed" not in md
+
+def test_future_iat():
+    n = int(time.time())
+    t = jwt.encode({**good(), "iat": n + 3600, "exp": n + 7200}, priv, algorithm="ES256", headers={"kid": "k1", "typ": "oauth-id-jag+jwt"})
+    with pytest.raises(AgentAuthError):
+        verify_id_jag(t, **opts())