cimdkit 0.1.0__py3-none-any.whl

cimdkit/__init__.py

@@ -0,0 +1,53 @@
+"""cimdkit: OAuth Client ID Metadata Documents (CIMD) for authorization servers.
+
+MCP clients identify themselves with a URL ``client_id`` instead of
+registering. cimdkit fetches that URL safely, validates the document against
+draft-ietf-oauth-client-id-metadata-document, caches it by its HTTP headers and
+matches redirect URIs, including the loopback any-port rule.
+"""
+
+from .document import ClientMetadata, Policy, make_document, validate_document
+from .errors import (
+    BlockedAddress,
+    CIMDError,
+    ClientIdMismatch,
+    FetchError,
+    InvalidClientId,
+    InvalidDocument,
+    InvalidRedirectUri,
+    TransientFetchError,
+)
+from .fetch import DEFAULT_MAX_BYTES, FetchResult, Response, fetch_document, is_public_address
+from .resolver import ClientResolver, cache_ttl
+from .urls import check_client_id_url, is_client_id_url, redirect_uri_matches
+
+__version__ = "0.1.0"
+
+#: Add these to your RFC 8414 authorization server metadata.
+SERVER_METADATA = {"client_id_metadata_document_supported": True}
+
+__all__ = [
+    "BlockedAddress",
+    "CIMDError",
+    "ClientIdMismatch",
+    "ClientMetadata",
+    "ClientResolver",
+    "DEFAULT_MAX_BYTES",
+    "FetchError",
+    "FetchResult",
+    "InvalidClientId",
+    "InvalidDocument",
+    "InvalidRedirectUri",
+    "Policy",
+    "Response",
+    "SERVER_METADATA",
+    "TransientFetchError",
+    "cache_ttl",
+    "check_client_id_url",
+    "fetch_document",
+    "is_client_id_url",
+    "is_public_address",
+    "make_document",
+    "redirect_uri_matches",
+    "validate_document",
+]

cimdkit/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

cimdkit/cli.py

@@ -0,0 +1,95 @@
+"""``cimdkit check``: test a Client ID Metadata Document the way a server will."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from typing import List, Optional
+
+from . import __version__
+from .document import Policy, validate_document
+from .errors import CIMDError
+from .fetch import DEFAULT_MAX_BYTES, fetch_document
+from .resolver import cache_ttl
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="cimdkit",
+        description="Check an OAuth Client ID Metadata Document (CIMD) as an authorization "
+                    "server would: fetch rules, spec rules and redirect URIs.")
+    p.add_argument("--version", action="version", version=f"cimdkit {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+    c = sub.add_parser("check", help="fetch (or read) and validate a metadata document")
+    c.add_argument("client_id", help="the Client Identifier URL")
+    c.add_argument("--file", help="validate this local JSON file instead of fetching the URL")
+    c.add_argument("--redirect-uri", action="append", default=[],
+                   help="also check that this redirect_uri would be accepted (repeatable)")
+    c.add_argument("--auth-method", action="append",
+                   help="auth methods the server supports (default: none, private_key_jwt)")
+    c.add_argument("--allow-loopback", action="store_true",
+                   help="allow fetching from 127.0.0.1 / ::1 (development only)")
+    c.add_argument("--max-bytes", type=int, default=DEFAULT_MAX_BYTES)
+    c.add_argument("--timeout", type=float, default=5.0)
+    c.add_argument("--json", action="store_true", help="print the result as JSON")
+    return p
+
+
+def _check(args: argparse.Namespace) -> int:
+    policy = Policy(auth_methods=tuple(args.auth_method)) if args.auth_method else Policy()
+    headers = {}
+    try:
+        if args.file:
+            with open(args.file, encoding="utf-8") as fh:
+                doc = json.load(fh)
+        else:
+            result = fetch_document(args.client_id, timeout=args.timeout,
+                                    max_bytes=args.max_bytes,
+                                    allow_loopback=args.allow_loopback)
+            doc, headers = result.document, dict(result.headers)
+        meta = validate_document(doc, args.client_id, policy)
+        bad = [u for u in args.redirect_uri if meta.match_redirect_uri(u) is None]
+    except CIMDError as exc:
+        kind = "transient" if exc.transient else "invalid_client"
+        if args.json:
+            print(json.dumps({"ok": False, "kind": kind, "error": str(exc)}))
+        else:
+            print(f"FAIL ({kind}): {exc}", file=sys.stderr)
+        return 1
+    except (OSError, ValueError) as exc:
+        print(f"FAIL: {exc}", file=sys.stderr)
+        return 1
+
+    ttl = cache_ttl(headers, now=time.time()) if headers else None
+    if args.json:
+        print(json.dumps({
+            "ok": not bad, "client_id": meta.client_id, "client_name": meta.client_name,
+            "host": meta.host, "redirect_uris": list(meta.redirect_uris),
+            "grant_types": list(meta.grant_types), "response_types": list(meta.response_types),
+            "token_endpoint_auth_method": meta.token_endpoint_auth_method,
+            "cache_seconds": ttl, "warnings": list(meta.warnings),
+            "rejected_redirect_uris": bad,
+        }, indent=2))
+    else:
+        print(f"{'OK' if not bad else 'FAIL'}  {meta.client_id}")
+        print(f"  name           {meta.display_name}  (host {meta.host})")
+        print(f"  auth method    {meta.token_endpoint_auth_method}")
+        print(f"  grant types    {', '.join(meta.grant_types)}")
+        for uri in meta.redirect_uris:
+            print(f"  redirect_uri   {uri}")
+        if ttl is not None:
+            print(f"  cache          {int(ttl)} s")
+        for w in meta.warnings:
+            print(f"  warning        {w}")
+        for uri in bad:
+            print(f"  rejected       {uri} is not a registered redirect_uri")
+    return 1 if bad else 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = _parser().parse_args(argv)
+    if args.command == "check":
+        return _check(args)
+    return 2  # pragma: no cover

cimdkit/document.py

@@ -0,0 +1,327 @@
+"""Validate a fetched Client ID Metadata Document against the spec and a server policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any, Iterable, List, Mapping, Optional, Sequence, Tuple
+
+from .errors import ClientIdMismatch, InvalidClientId, InvalidDocument, InvalidRedirectUri
+from .urls import (
+    _split,
+    check_client_id_url,
+    client_id_host,
+    find_redirect_uri,
+    is_loopback_redirect,
+)
+
+#: Shared-secret methods are forbidden: the document is public.
+SYMMETRIC_AUTH_METHODS = frozenset({"client_secret_post", "client_secret_basic", "client_secret_jwt"})
+
+#: JWK members that only appear in private or symmetric keys.
+PRIVATE_JWK_MEMBERS = frozenset({"d", "p", "q", "dp", "dq", "qi", "oth", "k"})
+
+#: Schemes never accepted in redirect_uris.
+FORBIDDEN_REDIRECT_SCHEMES = frozenset({"javascript", "data", "vbscript", "file", "about", "blob"})
+
+INFORMATIVE_URIS = ("client_uri", "logo_uri", "policy_uri", "tos_uri")
+
+
+@dataclass(frozen=True)
+class Policy:
+    """What this authorization server supports and allows.
+
+    ``auth_methods`` is in the server's terms; the client's own order of
+    preference (``token_endpoint_auth_methods_supported``) picks among them.
+    """
+
+    grant_types: Tuple[str, ...] = ("authorization_code", "refresh_token")
+    response_types: Tuple[str, ...] = ("code",)
+    auth_methods: Tuple[str, ...] = ("none", "private_key_jwt")
+    #: Ids the client_id must never equal: your issuer, trusted resource servers.
+    forbidden_client_ids: Tuple[str, ...] = ()
+    #: Require https redirect_uris to share the client_id's origin.
+    same_origin_redirects: bool = False
+    #: Accept http://localhost as a loopback redirect (127.0.0.1 and [::1] always are).
+    allow_localhost: bool = True
+    #: Accept a query in the client_id URL (the spec says SHOULD NOT, not MUST NOT).
+    allow_query: bool = True
+    #: Only accept client_ids on these hosts: "app.example.com" or "*.example.com".
+    #: Empty means any public host.
+    allowed_hosts: Tuple[str, ...] = ()
+
+    def host_allowed(self, host: str) -> bool:
+        if not self.allowed_hosts:
+            return True
+        host = host.lower().rstrip(".")
+        for pattern in self.allowed_hosts:
+            pattern = pattern.lower().rstrip(".")
+            if pattern.startswith("*."):
+                if host.endswith(pattern[1:]) and host != pattern[2:]:
+                    return True
+            elif host == pattern:
+                return True
+        return False
+
+
+@dataclass(frozen=True)
+class ClientMetadata:
+    """A validated client. ``raw`` keeps every property, including unknown ones."""
+
+    client_id: str
+    redirect_uris: Tuple[str, ...]
+    grant_types: Tuple[str, ...]
+    response_types: Tuple[str, ...]
+    token_endpoint_auth_method: str
+    client_name: Optional[str] = None
+    client_uri: Optional[str] = None
+    logo_uri: Optional[str] = None
+    policy_uri: Optional[str] = None
+    tos_uri: Optional[str] = None
+    scope: Optional[str] = None
+    jwks: Optional[Mapping[str, Any]] = None
+    jwks_uri: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+    #: Things that were dropped or look wrong but did not fail validation.
+    warnings: Tuple[str, ...] = ()
+    allow_localhost: bool = field(default=True, repr=False)
+
+    @property
+    def host(self) -> str:
+        """Show this next to the client name on the consent screen."""
+        return client_id_host(self.client_id)
+
+    @property
+    def display_name(self) -> str:
+        return self.client_name or self.host
+
+    def match_redirect_uri(self, redirect_uri: str) -> Optional[str]:
+        """The registered redirect URI that ``redirect_uri`` matches, or None."""
+        return find_redirect_uri(redirect_uri, self.redirect_uris,
+                                 allow_localhost=self.allow_localhost)
+
+    def check_redirect_uri(self, redirect_uri: Optional[str]) -> str:
+        """Return the redirect_uri to use, or raise :class:`InvalidRedirectUri`.
+
+        With no redirect_uri in the request, the only registered one is used
+        (RFC 6749 section 3.1.2.3); with several it is an error.
+        """
+        if redirect_uri is None:
+            if len(self.redirect_uris) == 1:
+                return self.redirect_uris[0]
+            raise InvalidRedirectUri("redirect_uri is required: the client registers several")
+        if self.match_redirect_uri(redirect_uri) is None:
+            raise InvalidRedirectUri(
+                f"redirect_uri {redirect_uri!r} is not listed in the client's metadata document")
+        return redirect_uri
+
+
+def _str_list(doc: Mapping[str, Any], key: str) -> Optional[List[str]]:
+    if key not in doc:
+        return None
+    value = doc[key]
+    if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+        raise InvalidDocument(f"{key} must be an array of strings")
+    return value
+
+
+def _opt_str(doc: Mapping[str, Any], key: str) -> Optional[str]:
+    value = doc.get(key)
+    if value is not None and not isinstance(value, str):
+        raise InvalidDocument(f"{key} must be a string")
+    return value
+
+
+def _origin(url: str) -> str:
+    scheme, netloc, _ = _split(url)
+    return f"{scheme}://{netloc.lower()}"
+
+
+def _check_redirect(uri: str, client_id: str, policy: Policy) -> None:
+    scheme, colon, _ = uri.partition(":")
+    if not colon or not scheme or not scheme[0].isalpha():
+        raise InvalidDocument(f"redirect_uri {uri!r} is not an absolute URI")
+    if "#" in uri:
+        raise InvalidDocument(f"redirect_uri {uri!r} must not contain a fragment")
+    lower = scheme.lower()
+    if lower in FORBIDDEN_REDIRECT_SCHEMES:
+        raise InvalidDocument(f"redirect_uri {uri!r} uses a forbidden scheme")
+    if lower == "http":
+        if not is_loopback_redirect(uri, allow_localhost=policy.allow_localhost):
+            raise InvalidDocument(f"redirect_uri {uri!r}: http is only allowed on loopback")
+    elif lower == "https":
+        try:
+            _split(uri)
+        except ValueError:
+            raise InvalidDocument(f"redirect_uri {uri!r} is not an absolute URI") from None
+        if policy.same_origin_redirects and _origin(uri) != _origin(client_id):
+            raise InvalidDocument(f"redirect_uri {uri!r} is not on the client_id's origin")
+    # Any other scheme is a private-use scheme for native apps (com.example.app:/cb).
+
+
+def _check_jwks(jwks: Any) -> None:
+    if not isinstance(jwks, dict) or not isinstance(jwks.get("keys"), list):
+        raise InvalidDocument('jwks must be an object with a "keys" array')
+    for key in jwks["keys"]:
+        if not isinstance(key, dict):
+            raise InvalidDocument("each key in jwks must be an object")
+        leaked = PRIVATE_JWK_MEMBERS.intersection(key)
+        if leaked:
+            raise InvalidDocument(
+                "jwks contains private or symmetric key material "
+                f"({', '.join(sorted(leaked))}); publish public keys only")
+
+
+def _choose_auth_method(doc: Mapping[str, Any], policy: Policy) -> str:
+    single = _opt_str(doc, "token_endpoint_auth_method")
+    several = _str_list(doc, "token_endpoint_auth_methods_supported")
+    declared = ([single] if single else []) + (several or [])
+    bad = SYMMETRIC_AUTH_METHODS.intersection(declared)
+    if bad:
+        raise InvalidDocument(
+            f"shared-secret auth method {sorted(bad)[0]!r} is not allowed in a public document")
+    if single and several is not None and single not in several:
+        raise InvalidDocument(
+            "token_endpoint_auth_method must be one of token_endpoint_auth_methods_supported")
+    if several is not None:
+        candidates = several
+    elif single:
+        candidates = [single]
+    else:
+        # The RFC 7591 default (client_secret_basic) must NOT be applied.
+        candidates = ["none"]
+    for method in candidates:
+        if method in policy.auth_methods:
+            return method
+    raise InvalidDocument(
+        f"no supported token endpoint auth method: client offers {candidates}, "
+        f"this server supports {list(policy.auth_methods)}")
+
+
+def _intersect(doc_values: Optional[List[str]], default: Sequence[str],
+               supported: Sequence[str], key: str) -> Tuple[str, ...]:
+    values = default if doc_values is None else doc_values
+    common = tuple(dict.fromkeys(v for v in values if v in supported))
+    if not common:
+        raise InvalidDocument(
+            f"none of the client's {key} {list(values)} are supported (server: {list(supported)})")
+    return common
+
+
+def validate_document(doc: Any, client_id: str, policy: Optional[Policy] = None) -> ClientMetadata:
+    """Check a parsed document fetched from ``client_id`` and return the client.
+
+    Raises :class:`InvalidClientId`, :class:`ClientIdMismatch` or
+    :class:`InvalidDocument`. Unknown properties are ignored, as the spec and
+    RFC 7591 require.
+    """
+    policy = policy or Policy()
+    check_client_id_url(client_id, allow_query=policy.allow_query)
+    if client_id in policy.forbidden_client_ids:
+        raise InvalidClientId("client_id must not equal the identifier of a trusted server")
+    if not policy.host_allowed(client_id_host(client_id)):
+        raise InvalidClientId(f"client_id host {client_id_host(client_id)!r} is not allowed here")
+    if not isinstance(doc, dict):
+        raise InvalidDocument("the metadata document must be a JSON object")
+
+    doc_id = doc.get("client_id")
+    if doc_id != client_id:
+        raise ClientIdMismatch(
+            f"document client_id {doc_id!r} does not exactly match the URL it was fetched "
+            f"from {client_id!r}")
+
+    for key in ("client_secret", "client_secret_expires_at"):
+        if key in doc:
+            raise InvalidDocument(f"{key} must not appear in a public metadata document")
+
+    method = _choose_auth_method(doc, policy)
+
+    jwks = doc.get("jwks")
+    jwks_uri = _opt_str(doc, "jwks_uri")
+    if jwks is not None and jwks_uri is not None:
+        raise InvalidDocument("jwks and jwks_uri must not both be present")
+    if jwks is not None:
+        _check_jwks(jwks)
+    if jwks_uri is not None and not jwks_uri.startswith("https://"):
+        raise InvalidDocument("jwks_uri must be an https URL")
+    if method == "private_key_jwt" and jwks is None and jwks_uri is None:
+        raise InvalidDocument("private_key_jwt needs jwks or jwks_uri in the document")
+
+    grant_types = _intersect(_str_list(doc, "grant_types"), ["authorization_code"],
+                             policy.grant_types, "grant_types")
+    response_types = _intersect(_str_list(doc, "response_types"), ["code"],
+                                policy.response_types, "response_types")
+
+    redirect_uris = _str_list(doc, "redirect_uris") or []
+    for uri in redirect_uris:
+        _check_redirect(uri, client_id, policy)
+    if "authorization_code" in grant_types and not redirect_uris:
+        raise InvalidDocument("redirect_uris is required for the authorization_code grant")
+
+    warnings: List[str] = []
+    informative = {}
+    for key in INFORMATIVE_URIS:
+        value = doc.get(key)
+        if value is None:
+            continue
+        if isinstance(value, str) and value.startswith("https://"):
+            informative[key] = value
+        else:
+            warnings.append(f"{key} ignored: only https URLs are shown to users")
+
+    name = doc.get("client_name")
+    if name is not None and not (isinstance(name, str) and name.strip()):
+        warnings.append("client_name ignored: not a non-empty string")
+        name = None
+
+    scope = doc.get("scope")
+    if scope is not None and not isinstance(scope, str):
+        warnings.append("scope ignored: not a string")
+        scope = None
+
+    if "?" in client_id:
+        warnings.append("client_id contains a query; the spec says it SHOULD NOT")
+
+    return ClientMetadata(
+        client_id=client_id,
+        redirect_uris=tuple(redirect_uris),
+        grant_types=grant_types,
+        response_types=response_types,
+        token_endpoint_auth_method=method,
+        client_name=name,
+        scope=scope,
+        jwks=MappingProxyType(jwks) if jwks is not None else None,
+        jwks_uri=jwks_uri,
+        raw=MappingProxyType(dict(doc)),
+        warnings=tuple(warnings),
+        allow_localhost=policy.allow_localhost,
+        **informative,
+    )
+
+
+def make_document(client_id: str, *, client_name: str, redirect_uris: Iterable[str],
+                  grant_types: Iterable[str] = ("authorization_code", "refresh_token"),
+                  response_types: Iterable[str] = ("code",),
+                  token_endpoint_auth_method: str = "none",
+                  **extra: Any) -> dict:
+    """Build a metadata document for a client to publish, and check it first.
+
+    Raises the same errors as :func:`validate_document` if the result would be
+    rejected by a compliant authorization server.
+    """
+    doc = {
+        "client_id": client_id,
+        "client_name": client_name,
+        "redirect_uris": list(redirect_uris),
+        "grant_types": list(grant_types),
+        "response_types": list(response_types),
+        "token_endpoint_auth_method": token_endpoint_auth_method,
+    }
+    doc.update(extra)
+    permissive = Policy(
+        grant_types=tuple(doc["grant_types"]),
+        response_types=tuple(doc["response_types"]),
+        auth_methods=(token_endpoint_auth_method,),
+    )
+    validate_document(doc, client_id, permissive)
+    return doc

cimdkit/errors.py

@@ -0,0 +1,68 @@
+"""Errors raised while resolving a Client ID Metadata Document.
+
+Every error carries the OAuth error code to return (``invalid_client``) and
+whether the failure is *transient* (network trouble: retry later, keep any
+cached metadata, answer 503) or *terminal* (the document is missing, wrong or
+rejected: drop cached metadata, answer ``invalid_client``).
+"""
+
+from __future__ import annotations
+
+from typing import Dict
+
+
+class CIMDError(Exception):
+    """Base class. The message is safe to show to the person signing in."""
+
+    #: OAuth error code for the token endpoint / authorization error page.
+    error = "invalid_client"
+    #: True for network problems: retry later and keep cached metadata.
+    transient = False
+    #: True when the spec says the client's refresh tokens should be revoked.
+    revoke_tokens = False
+
+    @property
+    def status_code(self) -> int:
+        """HTTP status the spec suggests at the token endpoint."""
+        return 503 if self.transient else 400
+
+    def to_oauth_error(self) -> Dict[str, str]:
+        """``{"error": ..., "error_description": ...}`` for a JSON error body."""
+        return {"error": self.error, "error_description": str(self)}
+
+
+class InvalidClientId(CIMDError):
+    """The client_id is not a valid Client Identifier URL, or is not allowed."""
+
+
+class InvalidDocument(CIMDError):
+    """The document was fetched but breaks the spec or this server's policy."""
+
+
+class ClientIdMismatch(InvalidDocument):
+    """The document's ``client_id`` is not exactly the URL it was fetched from."""
+
+    revoke_tokens = True
+
+
+class InvalidRedirectUri(CIMDError):
+    """The redirect_uri in an authorization request is not registered.
+
+    Never redirect to it: show the error to the user instead.
+    """
+
+    error = "invalid_request"
+
+
+class FetchError(CIMDError):
+    """The document could not be used: wrong status, too large, not JSON..."""
+
+
+class BlockedAddress(FetchError):
+    """The host resolves to a private or special-use address (SSRF guard)."""
+
+
+class TransientFetchError(CIMDError):
+    """Timeout, DNS or connection failure, or a 5xx/429 answer. Try again later."""
+
+    transient = True

cimdkit/fetch.py

@@ -0,0 +1,213 @@
+"""Fetch a Client ID Metadata Document the way the spec requires, safely.
+
+* https only, no redirects followed, ``Accept: application/json``;
+* every address the host resolves to must be public (no loopback, private,
+  link-local, CGNAT, multicast or reserved ranges, IPv4-mapped and NAT64
+  forms included), and the connection goes to the address that was checked,
+  so DNS rebinding cannot swap it afterwards;
+* at most ``max_bytes`` (5 KB by default) are read, under one overall deadline;
+* the body must be a JSON object with no duplicate keys.
+"""
+
+from __future__ import annotations
+
+import http.client
+import ipaddress
+import json
+import socket
+import ssl
+import time
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Mapping, Optional, Sequence
+
+from .errors import BlockedAddress, FetchError, TransientFetchError
+from .urls import _split, _split_netloc, check_client_id_url
+
+DEFAULT_MAX_BYTES = 5 * 1024
+DEFAULT_TIMEOUT = 5.0
+USER_AGENT = "cimdkit (+https://github.com/srikrishnaL/kitforge)"
+
+_NAT64 = ipaddress.ip_network("64:ff9b::/96")
+_TRANSIENT_STATUS = {408, 425, 429, 500, 502, 503, 504}
+
+Resolver = Callable[[str, int], Sequence[str]]
+
+
+@dataclass
+class Response:
+    status: int
+    headers: Dict[str, str]
+    body: bytes
+
+
+Transport = Callable[..., Response]
+
+
+@dataclass
+class FetchResult:
+    document: dict
+    headers: Mapping[str, str] = field(default_factory=dict)
+    address: str = ""
+
+
+def is_public_address(addr: str) -> bool:
+    """False for any special-use address (RFC 6890) an attacker could aim us at."""
+    try:
+        ip = ipaddress.ip_address(addr.split("%", 1)[0])
+    except ValueError:
+        return False
+    if ip.version == 6:
+        if ip.ipv4_mapped is not None:
+            return is_public_address(str(ip.ipv4_mapped))
+        if ip in _NAT64:
+            return is_public_address(str(ipaddress.IPv4Address(int(ip) & 0xFFFFFFFF)))
+        if ip.sixtofour is not None and not is_public_address(str(ip.sixtofour)):
+            return False
+        if ip.teredo is not None:
+            return False
+    return bool(ip.is_global) and not ip.is_multicast
+
+
+def _is_loopback(addr: str) -> bool:
+    try:
+        ip = ipaddress.ip_address(addr.split("%", 1)[0])
+    except ValueError:
+        return False
+    if ip.version == 6 and ip.ipv4_mapped is not None:
+        ip = ip.ipv4_mapped
+    return ip.is_loopback
+
+
+def system_resolver(host: str, port: int) -> List[str]:
+    infos = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
+    return list(dict.fromkeys(info[4][0] for info in infos))
+
+
+class _PinnedHTTPSConnection(http.client.HTTPSConnection):
+    """HTTPS to a fixed IP, with SNI and certificate checks for the real host name."""
+
+    def __init__(self, host: str, port: int, address: str, timeout: float,
+                 context: ssl.SSLContext) -> None:
+        super().__init__(host, port, timeout=timeout, context=context)
+        self._address = address
+        self._ctx = context
+
+    def connect(self) -> None:  # pragma: no cover - exercised by the TLS test
+        sock = socket.create_connection((self._address, self.port), self.timeout)
+        self.sock = self._ctx.wrap_socket(sock, server_hostname=self.host)
+
+
+def https_transport(*, host: str, port: int, address: str, target: str,
+                    headers: Mapping[str, str], timeout: float, max_bytes: int,
+                    ssl_context: Optional[ssl.SSLContext] = None) -> Response:
+    """Default transport: one GET over a pinned TLS connection, read with a deadline."""
+    deadline = time.monotonic() + timeout
+    ctx = ssl_context or ssl.create_default_context()
+    conn = _PinnedHTTPSConnection(host, port, address, timeout, ctx)
+    try:
+        conn.request("GET", target, headers=dict(headers))
+        resp = conn.getresponse()
+        got: Dict[str, str] = {}
+        for k, v in resp.getheaders():
+            k = k.lower()
+            got[k] = f"{got[k]}, {v}" if k in got else v
+        length = got.get("content-length", "")
+        if resp.status == 200 and length.isdigit() and int(length) > max_bytes:
+            raise FetchError(f"metadata document is {length} bytes; the limit is {max_bytes}")
+        chunks: List[bytes] = []
+        size = 0
+        while size <= max_bytes:
+            if time.monotonic() > deadline:
+                raise TransientFetchError("timed out reading the metadata document")
+            chunk = resp.read(min(1024, max_bytes + 1 - size))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            size += len(chunk)
+        return Response(resp.status, got, b"".join(chunks))
+    finally:
+        conn.close()
+
+
+def _no_duplicates(pairs):
+    out = {}
+    for key, value in pairs:
+        if key in out:
+            raise FetchError(f"metadata document repeats the property {key!r}")
+        out[key] = value
+    return out
+
+
+def _is_json_type(content_type: str) -> bool:
+    mime = content_type.split(";", 1)[0].strip().lower()
+    return mime == "application/json" or (mime.startswith("application/") and mime.endswith("+json"))
+
+
+def fetch_document(client_id: str, *, timeout: float = DEFAULT_TIMEOUT,
+                   max_bytes: int = DEFAULT_MAX_BYTES, allow_loopback: bool = False,
+                   require_json_content_type: bool = True,
+                   resolver: Optional[Resolver] = None,
+                   transport: Optional[Transport] = None,
+                   ssl_context: Optional[ssl.SSLContext] = None,
+                   user_agent: str = USER_AGENT) -> FetchResult:
+    """Fetch and parse the document at ``client_id``. It is not validated here.
+
+    ``allow_loopback`` lets a development server fetch from 127.0.0.1/::1; the
+    spec forbids that in production. ``resolver`` and ``transport`` are hooks
+    for tests and custom networking.
+    """
+    check_client_id_url(client_id)
+    _, netloc, rest = _split(client_id)
+    host, port_s, _ = _split_netloc(netloc)
+    port = int(port_s) if port_s else 443
+    bare = host[1:-1] if host.startswith("[") else host
+
+    try:
+        ipaddress.ip_address(bare)
+        addresses: Sequence[str] = [bare]
+    except ValueError:
+        try:
+            addresses = (resolver or system_resolver)(bare, port)
+        except (OSError, UnicodeError) as exc:
+            raise TransientFetchError(f"could not resolve {bare}: {exc}") from None
+    if not addresses:
+        raise TransientFetchError(f"{bare} has no addresses")
+    for addr in addresses:
+        if is_public_address(addr) or (allow_loopback and _is_loopback(addr)):
+            continue
+        raise BlockedAddress(
+            f"{bare} resolves to {addr}, a private or special-use address; refusing to fetch it")
+
+    headers = {"Accept": "application/json", "User-Agent": user_agent, "Host": netloc}
+    try:
+        resp = (transport or https_transport)(
+            host=bare, port=port, address=addresses[0], target=rest, headers=headers,
+            timeout=timeout, max_bytes=max_bytes, ssl_context=ssl_context)
+    except (FetchError, TransientFetchError):
+        raise
+    except ssl.SSLCertVerificationError as exc:
+        raise FetchError(f"TLS certificate for {bare} is not valid: {exc.verify_message}") from None
+    except (OSError, http.client.HTTPException) as exc:
+        raise TransientFetchError(f"could not fetch {client_id}: {exc}") from None
+
+    if resp.status != 200:
+        if 300 <= resp.status < 400:
+            raise FetchError(f"{client_id} answered {resp.status}; redirects are not followed")
+        if resp.status in _TRANSIENT_STATUS:
+            raise TransientFetchError(f"{client_id} answered {resp.status}")
+        raise FetchError(f"{client_id} answered {resp.status}, not 200")
+    if len(resp.body) > max_bytes:
+        raise FetchError(f"metadata document is larger than {max_bytes} bytes")
+    ctype = resp.headers.get("content-type", "")
+    if require_json_content_type and not _is_json_type(ctype):
+        raise FetchError(f"metadata document is served as {ctype or 'no content type'!r}, "
+                         "not application/json")
+    try:
+        doc = json.loads(resp.body.decode("utf-8"), object_pairs_hook=_no_duplicates)
+    except FetchError:
+        raise
+    except (UnicodeDecodeError, ValueError) as exc:
+        raise FetchError(f"metadata document is not valid JSON: {exc}") from None
+    if not isinstance(doc, dict):
+        raise FetchError("metadata document must be a JSON object")
+    return FetchResult(doc, resp.headers, addresses[0])

cimdkit/resolver.py

@@ -0,0 +1,143 @@
+"""Resolve a client_id to validated metadata, with spec-compliant caching."""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+from email.utils import parsedate_to_datetime
+from typing import Callable, Dict, Mapping, Optional
+
+from .document import ClientMetadata, Policy, validate_document
+from .errors import CIMDError, InvalidClientId, TransientFetchError
+from .fetch import FetchResult, fetch_document
+from .urls import check_client_id_url, client_id_host
+
+
+def _directives(cache_control: str) -> Dict[str, Optional[str]]:
+    out: Dict[str, Optional[str]] = {}
+    for part in cache_control.split(","):
+        name, eq, value = part.strip().partition("=")
+        if name:
+            out[name.strip().lower()] = value.strip().strip('"') if eq else None
+    return out
+
+
+def _http_date(value: Optional[str]) -> Optional[float]:
+    if not value:
+        return None
+    try:
+        return parsedate_to_datetime(value).timestamp()
+    except (TypeError, ValueError, IndexError, OverflowError):
+        return None
+
+
+def cache_ttl(headers: Mapping[str, str], *, now: float, default_ttl: float = 300,
+              min_ttl: float = 0, max_ttl: float = 86400) -> float:
+    """Seconds to keep a document, from its HTTP cache headers (RFC 9111).
+
+    ``no-store``/``no-cache`` mean 0 (unless ``min_ttl`` says otherwise),
+    ``s-maxage`` beats ``max-age`` (an authorization server is a shared cache),
+    ``Age`` is subtracted, ``Expires`` is used only without either, and
+    ``default_ttl`` applies when nothing is said. The result is clamped to
+    ``[min_ttl, max_ttl]``.
+    """
+    headers = {k.lower(): v for k, v in headers.items()}
+    cc = _directives(headers.get("cache-control", ""))
+    if "no-store" in cc or "no-cache" in cc or "private" in cc:
+        ttl: float = 0
+    else:
+        raw = cc.get("s-maxage") if "s-maxage" in cc else cc.get("max-age")
+        if raw is not None or "s-maxage" in cc or "max-age" in cc:
+            ttl = int(raw) if raw and raw.isdigit() else 0
+            age = headers.get("age", "")
+            if age.isdigit():
+                ttl -= int(age)
+        elif "expires" in headers:
+            expires = _http_date(headers["expires"])
+            date = _http_date(headers.get("date")) or now
+            ttl = expires - date if expires is not None else 0
+        else:
+            ttl = default_ttl
+    return max(min_ttl, min(max_ttl, ttl))
+
+
+@dataclass
+class _Entry:
+    metadata: ClientMetadata
+    expires: float
+
+
+class ClientResolver:
+    """Fetch, validate and cache Client ID Metadata Documents.
+
+    >>> resolver = ClientResolver(Policy(forbidden_client_ids=("https://auth.example.com",)))
+    >>> client = resolver.resolve(request.args["client_id"])  # doctest: +SKIP
+    >>> client.check_redirect_uri(request.args.get("redirect_uri"))  # doctest: +SKIP
+
+    * A valid document is cached for as long as its cache headers allow,
+      clamped to ``[min_ttl, max_ttl]``. Invalid documents and errors are never cached.
+    * On a transient failure (timeout, 5xx) a previously valid document is
+      kept and returned, as the spec asks; it is retried after ``retry_after``.
+    * On a terminal failure the cached document is dropped and the error raised.
+      Check ``error.revoke_tokens`` to see if the client's refresh tokens must go.
+
+    Extra keyword arguments go to :func:`cimdkit.fetch_document`
+    (``timeout``, ``max_bytes``, ``allow_loopback``...). Thread-safe.
+    """
+
+    def __init__(self, policy: Optional[Policy] = None, *,
+                 fetch: Optional[Callable[[str], FetchResult]] = None,
+                 default_ttl: float = 300, min_ttl: float = 0, max_ttl: float = 86400,
+                 retry_after: float = 30, clock: Callable[[], float] = time.time,
+                 **fetch_options) -> None:
+        self.policy = policy or Policy()
+        self._fetch = fetch or (lambda cid: fetch_document(cid, **fetch_options))
+        self.default_ttl, self.min_ttl, self.max_ttl = default_ttl, min_ttl, max_ttl
+        self.retry_after = retry_after
+        self._clock = clock
+        self._cache: Dict[str, _Entry] = {}
+        self._lock = threading.Lock()
+
+    def cached(self, client_id: str) -> Optional[ClientMetadata]:
+        """The cached metadata, fresh or stale, without fetching."""
+        with self._lock:
+            entry = self._cache.get(client_id)
+        return entry.metadata if entry else None
+
+    def invalidate(self, client_id: str) -> None:
+        with self._lock:
+            self._cache.pop(client_id, None)
+
+    def resolve(self, client_id: str, *, force: bool = False) -> ClientMetadata:
+        """Return validated metadata for ``client_id`` or raise a :class:`CIMDError`."""
+        now = self._clock()
+        with self._lock:
+            entry = self._cache.get(client_id)
+        if entry and not force and now < entry.expires:
+            return entry.metadata
+        try:
+            # Check the URL and host policy before any network traffic.
+            check_client_id_url(client_id, allow_query=self.policy.allow_query)
+            if not self.policy.host_allowed(client_id_host(client_id)):
+                raise InvalidClientId(
+                    f"client_id host {client_id_host(client_id)!r} is not allowed here")
+            result = self._fetch(client_id)
+            metadata = validate_document(result.document, client_id, self.policy)
+        except TransientFetchError:
+            if entry is None:
+                raise
+            with self._lock:
+                entry.expires = now + self.retry_after
+            return entry.metadata
+        except CIMDError:
+            self.invalidate(client_id)
+            raise
+        ttl = cache_ttl(result.headers, now=now, default_ttl=self.default_ttl,
+                        min_ttl=self.min_ttl, max_ttl=self.max_ttl)
+        with self._lock:
+            if ttl > 0:
+                self._cache[client_id] = _Entry(metadata, now + ttl)
+            else:
+                self._cache.pop(client_id, None)
+        return metadata

cimdkit/urls.py

@@ -0,0 +1,146 @@
+"""Client Identifier URL checks and loopback-aware redirect_uri matching."""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable, Optional, Tuple
+
+from .errors import InvalidClientId
+
+#: Hosts that get the RFC 8252 / RFC 9700 "any port" exception for http redirects.
+LOOPBACK_IPS = ("127.0.0.1", "[::1]")
+
+_DOT_SEGMENT = re.compile(r"^(?:\.|%2e){1,2}$", re.IGNORECASE)
+
+
+def is_client_id_url(value: object) -> bool:
+    """True if ``value`` should be treated as a Client Identifier URL.
+
+    Use it to route between pre-registered clients (random ids) and CIMD
+    clients: the spec asks servers never to issue ids starting with https://.
+    """
+    return isinstance(value, str) and value.startswith("https://")
+
+
+def _split_netloc(netloc: str) -> Tuple[str, Optional[str], Optional[str]]:
+    """Split ``user@host:port`` into (host, port, userinfo) without normalizing."""
+    userinfo = None
+    if "@" in netloc:
+        userinfo, _, netloc = netloc.rpartition("@")
+    if netloc.startswith("["):
+        end = netloc.find("]")
+        if end == -1:
+            raise ValueError("unclosed IPv6 bracket")
+        host, rest = netloc[: end + 1], netloc[end + 1 :]
+        if rest and not rest.startswith(":"):
+            raise ValueError("junk after IPv6 address")
+        port = rest[1:] if rest else None
+    elif ":" in netloc:
+        host, _, port = netloc.partition(":")
+    else:
+        host, port = netloc, None
+    return host, port, userinfo
+
+
+def _split(url: str) -> Tuple[str, str, str]:
+    """Split an absolute URL into (scheme, netloc, rest) exactly as written."""
+    scheme, sep, after = url.partition("://")
+    if not sep:
+        raise ValueError("not an absolute URL with an authority")
+    cut = len(after)
+    for ch in "/?#":
+        i = after.find(ch)
+        if i != -1:
+            cut = min(cut, i)
+    return scheme, after[:cut], after[cut:]
+
+
+def _valid_port(port: Optional[str]) -> bool:
+    return port is None or (port.isdigit() and port.isascii() and 0 < int(port) < 65536)
+
+
+def check_client_id_url(value: object, *, allow_query: bool = True) -> str:
+    """Raise :class:`InvalidClientId` unless ``value`` is a valid Client Identifier URL.
+
+    Rules (draft-ietf-oauth-client-id-metadata-document, section 3): https
+    scheme, no userinfo, a path other than ``/``, no ``.`` or ``..`` segments,
+    no fragment, and (SHOULD) no query. The URL is not normalized: the server
+    must compare it as an exact string.
+    """
+    if not isinstance(value, str) or not value:
+        raise InvalidClientId("client_id must be a non-empty string")
+    if any(ord(c) <= 0x20 or ord(c) == 0x7F for c in value):
+        raise InvalidClientId("client_id contains spaces or control characters")
+    if not value.startswith("https://"):
+        raise InvalidClientId("client_id URL must start with https://")
+    if "#" in value:
+        raise InvalidClientId("client_id URL must not contain a fragment")
+    try:
+        _, netloc, rest = _split(value)
+        host, port, userinfo = _split_netloc(netloc)
+    except ValueError as exc:
+        raise InvalidClientId(f"client_id URL is malformed: {exc}") from None
+    if userinfo is not None:
+        raise InvalidClientId("client_id URL must not contain a username or password")
+    if not host:
+        raise InvalidClientId("client_id URL has no host")
+    if not _valid_port(port):
+        raise InvalidClientId("client_id URL has an invalid port")
+    path, _, query = rest.partition("?")
+    if path in ("", "/"):
+        raise InvalidClientId("client_id URL must have a path other than /")
+    if any(_DOT_SEGMENT.match(seg) for seg in path.split("/")):
+        raise InvalidClientId("client_id URL must not contain . or .. path segments")
+    if "?" in rest and not allow_query:
+        raise InvalidClientId("client_id URL must not contain a query")
+    return value
+
+
+def client_id_host(client_id: str) -> str:
+    """The host to show on the consent screen (the spec asks servers to show it)."""
+    _, netloc, _ = _split(client_id)
+    host, _, _ = _split_netloc(netloc)
+    return host.lower()
+
+
+def is_loopback_redirect(uri: str, *, allow_localhost: bool = True) -> bool:
+    """True for ``http://127.0.0.1``, ``http://[::1]`` (and ``http://localhost``) URIs."""
+    try:
+        scheme, netloc, _ = _split(uri)
+        host, port, userinfo = _split_netloc(netloc)
+    except ValueError:
+        return False
+    if scheme != "http" or userinfo is not None or not _valid_port(port):
+        return False
+    hosts = LOOPBACK_IPS + (("localhost",) if allow_localhost else ())
+    return host.lower() in hosts
+
+
+def redirect_uri_matches(requested: str, registered: str, *, allow_localhost: bool = True) -> bool:
+    """Exact string match, except that loopback http redirects may use any port.
+
+    Native apps and CLIs (Claude Code, VS Code, MCP Inspector) listen on a random
+    port, so ``http://127.0.0.1:53123/callback`` matches a registered
+    ``http://127.0.0.1/callback`` or ``http://127.0.0.1:8080/callback``
+    (RFC 8252 section 7.3, RFC 9700 section 4.1.3). Host, path and query
+    must still match exactly.
+    """
+    if requested == registered:
+        return True
+    if not (is_loopback_redirect(requested, allow_localhost=allow_localhost)
+            and is_loopback_redirect(registered, allow_localhost=allow_localhost)):
+        return False
+    _, r_netloc, r_rest = _split(requested)
+    _, g_netloc, g_rest = _split(registered)
+    r_host = _split_netloc(r_netloc)[0].lower()
+    g_host = _split_netloc(g_netloc)[0].lower()
+    return r_host == g_host and r_rest == g_rest
+
+
+def find_redirect_uri(requested: str, registered: Iterable[str], *,
+                      allow_localhost: bool = True) -> Optional[str]:
+    """The registered URI that ``requested`` matches, or None."""
+    for uri in registered:
+        if redirect_uri_matches(requested, uri, allow_localhost=allow_localhost):
+            return uri
+    return None

cimdkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: cimdkit
+Version: 0.1.0
+Summary: OAuth Client ID Metadata Documents (CIMD) for authorization servers: safe fetch, spec validation, caching and redirect_uri matching for MCP clients
+Project-URL: Homepage, https://github.com/srikrishnaL/kitforge/tree/main/packages/cimdkit
+Project-URL: Source, https://github.com/srikrishnaL/kitforge
+Project-URL: Issues, https://github.com/srikrishnaL/kitforge/issues
+Project-URL: Changelog, https://github.com/srikrishnaL/kitforge/blob/main/packages/cimdkit/CHANGELOG.md
+Author: Sri Krishna Lingamaneni
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authorization server,cimd,client id metadata document,client_id,dynamic client registration,mcp,model context protocol,oauth,oauth2,ssrf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# cimdkit
+
+OAuth **Client ID Metadata Documents** (CIMD) for Python authorization servers.
+
+MCP clients such as Claude Code and VS Code no longer register with your OAuth server: they
+send a URL as their `client_id`, and your server has to fetch that URL, validate the JSON it
+finds there and remember it. Doing that safely is fiddly (SSRF, redirects, exact-match rules,
+caching, the loopback port exception), and every server is writing it again from scratch.
+cimdkit does it in one call, with no dependencies.
+
+```bash
+pip install cimdkit
+```
+
+Python 3.9+. Works with any web framework and any OAuth library (Authlib, FastMCP's OAuth
+proxy, your own).
+
+## Use it in your `/authorize` endpoint
+
+```python
+from cimdkit import ClientResolver, CIMDError, Policy, SERVER_METADATA, is_client_id_url
+
+resolver = ClientResolver(Policy(
+    forbidden_client_ids=("https://auth.example.com",),  # your own issuer
+    auth_methods=("none", "private_key_jwt"),
+))
+
+def authorize(params):
+    client_id = params["client_id"]
+    if not is_client_id_url(client_id):
+        return handle_preregistered_client(params)       # your existing clients
+    try:
+        client = resolver.resolve(client_id)             # fetch + validate + cache
+        redirect_uri = client.check_redirect_uri(params.get("redirect_uri"))
+    except CIMDError as err:
+        # Never redirect on these errors: show them to the user.
+        return render_error(err.to_oauth_error(), status=err.status_code)
+    return render_consent(name=client.display_name, host=client.host, logo=client.logo_uri,
+                          redirect_uri=redirect_uri)
+
+# And advertise support in /.well-known/oauth-authorization-server:
+metadata.update(SERVER_METADATA)   # {"client_id_metadata_document_supported": True}
+```
+
+At the token endpoint, call `resolver.resolve(client_id)` again (it is served from the cache)
+and use `client.token_endpoint_auth_method`: `"none"` means a public PKCE client, so reject any
+client authentication it sends; `"private_key_jwt"` means verify its assertion against
+`client.jwks` or `client.jwks_uri`. On a `TransientFetchError` answer 503; on any other
+`CIMDError` answer `invalid_client`, and if `err.revoke_tokens` is true, revoke the client's
+refresh tokens (the document now names a different client).
+
+## What it checks
+
+**The URL** (`check_client_id_url`): https, a path other than `/`, no userinfo, no `.`/`..`
+segments (including `%2e`), no fragment, a valid port. Compared as an exact string, never
+normalized.
+
+**The fetch** (`fetch_document`):
+
+- Every address the host resolves to must be public. Loopback, private, link-local (including
+  the cloud metadata address `169.254.169.254`), CGNAT, multicast and reserved ranges are
+  refused, also when hidden as IPv4-mapped IPv6, NAT64 or 6to4.
+- The connection goes to the exact address that was checked, with SNI and certificate checks
+  for the real host name, so DNS rebinding cannot swap the address between check and connect.
+- Redirects are not followed. Only `200` is accepted; `5xx`, `408` and `429` are reported as
+  transient.
+- `Accept: application/json`, at most 5 KB read, one overall deadline, `application/json` (or
+  `application/*+json`) content type, and a JSON object with no duplicate keys.
+
+**The document** (`validate_document`):
+
+- `client_id` must exactly equal the URL it was fetched from.
+- No `client_secret`, no shared-secret auth methods (`client_secret_basic`, `_post`, `_jwt`),
+  no private key material in `jwks`, not both `jwks` and `jwks_uri`.
+- With no auth method declared, the method is `none` (not RFC 7591's `client_secret_basic`).
+  With `token_endpoint_auth_methods_supported`, the client's first method that you support is
+  chosen.
+- `grant_types` and `response_types` are intersected with what you support; an empty result
+  is an error.
+- `redirect_uris`: absolute, no fragment, no `javascript:`/`data:`/`file:`, plain `http` only
+  on loopback. Private-use schemes for native apps (`com.example.app:/cb`) are allowed.
+- Unknown properties are ignored, not rejected. Informative URLs (`logo_uri`, `client_uri`...)
+  that are not https are dropped with a warning instead of failing the whole sign-in.
+
+**Redirect URIs** (`client.check_redirect_uri`): exact match, except that
+`http://127.0.0.1`, `http://[::1]` and `http://localhost` redirects may use any port, as RFC
+8252 and RFC 9700 require for native apps and CLIs that listen on a random port.
+
+**Caching** (`ClientResolver`): valid documents are kept for as long as `Cache-Control`
+(`s-maxage`, `max-age`, `Age`, `no-store`...) or `Expires` allow, clamped to
+`[min_ttl, max_ttl]` (default 0 s to 24 h, 5 minutes when the response says nothing). Errors
+and invalid documents are never cached. A transient failure keeps serving the last good
+document; a terminal failure drops it.
+
+**Your policy** (`Policy`): supported grant types, response types and auth methods, ids the
+client_id must never equal (your issuer, trusted resource servers), `allowed_hosts`
+(`"*.example.com"`) to accept only trusted client domains, same-origin redirects, and whether
+`localhost` counts as loopback.
+
+## Check your own client's document
+
+If you publish a CIMD for your MCP client, check it the way servers will:
+
+```console
+$ cimdkit check https://app.example.com/oauth/client.json --redirect-uri http://127.0.0.1:53682/callback
+OK  https://app.example.com/oauth/client.json
+  name           Example Agent  (host app.example.com)
+  auth method    none
+  grant types    authorization_code, refresh_token
+  redirect_uri   http://127.0.0.1/callback
+  cache          3600 s
+```
+
+`--file client.json` checks a local file before you deploy it, and `--json` prints the result
+for CI. Or build the document in Python and get an error if any server would reject it:
+
+```python
+from cimdkit import make_document
+
+doc = make_document("https://app.example.com/oauth/client.json",
+                    client_name="Example Agent",
+                    redirect_uris=["http://127.0.0.1/callback"],
+                    logo_uri="https://app.example.com/logo.png")
+```
+
+## For development
+
+`ClientResolver(allow_loopback=True)` (or `cimdkit check --allow-loopback`) lets a server on
+your machine fetch documents from `127.0.0.1`/`::1`. The spec forbids this in production.
+
+## Limits
+
+- It resolves and validates clients. It does not issue codes or tokens, verify
+  `private_key_jwt` assertions, or fetch `jwks_uri` and logos for you.
+- The fetch connects directly and ignores `HTTPS_PROXY`. Pass your own `transport=` to
+  `ClientResolver`/`fetch_document` if your server must use a proxy.
+- The cache is in memory, per process. Pass `fetch=` or wrap `resolve` to share one.
+- It follows draft-ietf-oauth-client-id-metadata-document as of November 2026. The draft can
+  still change.
+
+## Why this exists
+
+MCP's authorization spec made CIMD the default way for clients to identify themselves
+([SEP-991](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/991)), and
+authorization servers in every language are being asked to support it:
+
+- [modelcontextprotocol/python-sdk#1801](https://github.com/modelcontextprotocol/python-sdk/issues/1801): implement server-side CIMD support
+- [authlib/authlib#900](https://github.com/authlib/authlib/issues/900): support Client ID Metadata Document?
+- [ory/hydra#4061](https://github.com/ory/hydra/issues/4061), [supabase/auth#2850](https://github.com/supabase/auth/issues/2850), [spring-security#18375](https://github.com/spring-projects/spring-security/issues/18375), [LibreChat#16627](https://github.com/LibreChat-AI/LibreChat/issues/16627), [doorkeeper#1875](https://github.com/doorkeeper-gem/doorkeeper/issues/1875)
+
+The first implementations keep hitting the same bugs, each one a test here:
+unknown properties rejected ([keycloak#51236](https://github.com/keycloak/keycloak/issues/51236)),
+loopback redirect ports
+([claude-code#37747](https://github.com/anthropics/claude-code/issues/37747)), private-use
+redirect schemes rejected ([fastmcp#6336](https://github.com/PrefectHQ/fastmcp/issues/6336)), a
+malformed port causing a 500 ([fastmcp#5764](https://github.com/PrefectHQ/fastmcp/issues/5764)),
+no way to limit CIMD to trusted domains
+([fastmcp#6153](https://github.com/PrefectHQ/fastmcp/issues/6153)), and partial client_id URL
+validation ([python-sdk#3768](https://github.com/modelcontextprotocol/python-sdk/issues/3768)).
+
+## License
+
+MIT

cimdkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+cimdkit/__init__.py,sha256=kqVlNW9zsa7gBAeK6-I_WKzBL9i3tHQtZskqdL43A2I,1537
+cimdkit/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+cimdkit/cli.py,sha256=JTS8yEioa6ZNBuchI-9qMM2SOsIj0JzETIFd5-vBoXY,4251
+cimdkit/document.py,sha256=QrcA7R-ProP2lrqffm5pSkHAfTGXQdmJdHOdl8HEI6s,13543
+cimdkit/errors.py,sha256=n6dzyW7eeTMEolcuaTdqHKSgwmFLGpio1VxLz6K-R1o,2157
+cimdkit/fetch.py,sha256=Brd3fpsdhRDFjd9ecmfS5bj69A1CAPoKMNvsZgYBUdk,8514
+cimdkit/resolver.py,sha256=l3ynHscAEb-wzSVHZWUaQ15rRyCTKTOmTwccUSmbqgg,6069
+cimdkit/urls.py,sha256=my7BGfsToFtzxuXXnF3XVIcYGssRHYX7ZQXftZG_zWc,5961
+cimdkit-0.1.0.dist-info/METADATA,sha256=PnXj6E7hh4GguEzl2QH1tCtzRwbiArZlfDSI0EEz9wk,9668
+cimdkit-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+cimdkit-0.1.0.dist-info/entry_points.txt,sha256=4XHQyFhqT992dLDJaZFm8CZd-e29MwiVOqOpBJQw1kg,45
+cimdkit-0.1.0.dist-info/licenses/LICENSE,sha256=fl9U1idgeyJw-8GWneEYxVzZM_C29cBR63IAlNv7KjE,1080
+cimdkit-0.1.0.dist-info/RECORD,,

cimdkit-0.1.0.dist-info/WHEEL

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

cimdkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cimdkit = cimdkit.cli:main

cimdkit-0.1.0.dist-info/licenses/LICENSE

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