cimdkit 0.1.0__tar.gz

cimdkit-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+node_modules/
+coverage/
+.DS_Store

cimdkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.0 (2026-11-08)
+
+First release.
+
+- `ClientResolver`: resolve a URL `client_id` to validated client metadata, cached by the
+  response's HTTP cache headers, keeping the last good document on transient failures and
+  dropping it on terminal ones.
+- `fetch_document`: https only, no redirects, `Accept: application/json`, 5 KB limit, one
+  deadline, SSRF guard on every resolved address (IPv4-mapped, NAT64 and 6to4 included) with
+  the connection pinned to the checked address.
+- `validate_document`: exact client_id match, no secrets or shared-secret auth methods, no
+  private keys, auth method selection with the `none` default, grant and response type
+  intersection, redirect URI rules, unknown properties ignored.
+- `redirect_uri_matches` / `ClientMetadata.check_redirect_uri`: exact match with the loopback
+  any-port exception.
+- `Policy`: supported methods and grants, forbidden ids (your issuer), `allowed_hosts`,
+  same-origin redirects.
+- `make_document` and the `cimdkit check` command for client authors publishing a document.

cimdkit-0.1.0/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.

cimdkit-0.1.0/PKG-INFO

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

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

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cimdkit"
+version = "0.1.0"
+description = "OAuth Client ID Metadata Documents (CIMD) for authorization servers: safe fetch, spec validation, caching and redirect_uri matching for MCP clients"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Sri Krishna Lingamaneni" }]
+keywords = [
+  "oauth", "oauth2", "cimd", "client id metadata document", "client_id", "mcp",
+  "model context protocol", "authorization server", "dynamic client registration", "ssrf",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Security",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/srikrishnaL/kitforge/tree/main/packages/cimdkit"
+Source = "https://github.com/srikrishnaL/kitforge"
+Issues = "https://github.com/srikrishnaL/kitforge/issues"
+Changelog = "https://github.com/srikrishnaL/kitforge/blob/main/packages/cimdkit/CHANGELOG.md"
+
+[project.scripts]
+cimdkit = "cimdkit.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cimdkit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cimdkit-0.1.0/src/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-0.1.0/src/cimdkit/__main__.py

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

cimdkit-0.1.0/src/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