Add client_id to OAuth Resource Metadata and bump version to 0.1.19

Add optional client_id field to OAuthResourceMetadata (server) and
OAuthResourceMetadataResponse (client) as a custom RFC 9728 extension
for MCP compatibility. Includes WWW-Authenticate header support,
parse_client_id() helper, URL-safe validation, and documentation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rustyconover

docs/api/oauth.md

@@ -47,7 +47,7 @@ with http_connect(MyService, "https://api.example.com") as svc:
 ## How It Works
 
 1. Server serves `/.well-known/oauth-protected-resource` (RFC 9728)
-2. 401 responses include `WWW-Authenticate: Bearer resource_metadata="..."`
+2. 401 responses include `WWW-Authenticate: Bearer resource_metadata="..."` (and optionally `client_id="..."`)
 3. Client fetches metadata to discover authorization server(s)
 4. Client authenticates with the AS and sends Bearer token
 
@@ -57,19 +57,21 @@ If a client doesn't know the server's auth requirements upfront, it can
 discover them from a 401 response:
 
 ```python
-from vgi_rpc.http import parse_resource_metadata_url, fetch_oauth_metadata
+from vgi_rpc.http import parse_resource_metadata_url, parse_client_id, fetch_oauth_metadata
 
 # 1. Make a request that returns 401
 resp = client.post("/vgi/my_method", ...)
 
-# 2. Parse the metadata URL from WWW-Authenticate header
+# 2. Parse the metadata URL and optional client_id from WWW-Authenticate header
 www_auth = resp.headers["www-authenticate"]
 metadata_url = parse_resource_metadata_url(www_auth)
 # "https://api.example.com/.well-known/oauth-protected-resource/vgi"
+client_id = parse_client_id(www_auth)  # e.g. "my-app" or None
 
 # 3. Fetch the metadata
 meta = fetch_oauth_metadata(metadata_url)
 print(meta.authorization_servers)  # use these to authenticate
+print(meta.client_id)  # also available from the metadata document
 ```
 
 ## OAuthResourceMetadata
@@ -88,6 +90,7 @@ Pass to `make_wsgi_app(oauth_resource_metadata=...)` to enable OAuth discovery.
 | `resource_documentation` | `str \| None` | No | URL to developer docs |
 | `resource_policy_uri` | `str \| None` | No | URL to privacy policy |
 | `resource_tos_uri` | `str \| None` | No | URL to terms of service |
+| `client_id` | `str \| None` | No | OAuth client_id for auth server *(custom extension, not in RFC 9728)* |
 
 Raises `ValueError` if `resource` is empty or `authorization_servers` is empty.
 
@@ -271,17 +274,31 @@ url = parse_resource_metadata_url('Bearer resource_metadata="https://..."')
 
 Returns `None` if the header doesn't contain `resource_metadata`.
 
+## parse_client_id()
+
+Extract the `client_id` from a `WWW-Authenticate` header. Custom extension (not in RFC 9728).
+
+```python
+from vgi_rpc.http import parse_client_id
+
+client_id = parse_client_id('Bearer resource_metadata="https://...", client_id="my-app"')
+# "my-app"
+```
+
+Returns `None` if the header doesn't contain `client_id`.
+
 ## OAuthResourceMetadataResponse
 
 Frozen dataclass returned by `http_oauth_metadata()` and `fetch_oauth_metadata()`.
-Same fields as `OAuthResourceMetadata` (the server-side config class).
+Same fields as `OAuthResourceMetadata` (the server-side config class), including `client_id`.
 
 ## Standards Compliance
 
 - [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) — OAuth 2.0 Protected Resource Metadata
 - [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) — OAuth 2.0 Authorization Server Metadata
 - [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750) — Bearer Token Usage
 - Compatible with MCP's OAuth implementation
+- **Custom extension**: `client_id` field on `OAuthResourceMetadata` / `OAuthResourceMetadataResponse` and in `WWW-Authenticate` headers is not defined in RFC 9728
 
 ## Installation
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-rpc"
-version = "0.1.18"
+version = "0.1.19"
 description = "Vector Gateway Interface - RPC framework based on Apache Arrow"
 readme = "README.md"
 requires-python = ">=3.13"

tests/test_oauth.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+import dataclasses
 import json
 import time
 from collections.abc import Callable
@@ -24,6 +25,7 @@
     http_oauth_metadata,
     jwt_authenticate,
     make_sync_client,
+    parse_client_id,
     parse_resource_metadata_url,
 )
 
@@ -120,6 +122,8 @@ def authenticate(req: falcon.Request) -> AuthContext:
     resource_name="Test Service",
 )
 
+_METADATA_WITH_CLIENT_ID = dataclasses.replace(_METADATA, client_id="my-client-id")
+
 
 # ---------------------------------------------------------------------------
 # TestOAuthResourceMetadata
@@ -183,6 +187,7 @@ def test_well_known_omits_default_fields(self) -> None:
         assert "scopes_supported" not in d
         assert "bearer_methods_supported" not in d
         assert "resource_name" not in d
+        assert "client_id" not in d
 
     def test_well_known_exempt_from_auth(self) -> None:
         """Well-known endpoint is accessible even with auth enabled."""
@@ -287,6 +292,91 @@ def test_parse_resource_metadata_url_missing(self) -> None:
         assert parse_resource_metadata_url("Basic realm=test") is None
         assert parse_resource_metadata_url("") is None
 
+    def test_client_id_rejects_unsafe_characters(self) -> None:
+        """client_id with non-URL-safe characters raises ValueError."""
+        with pytest.raises(ValueError, match="URL-safe"):
+            OAuthResourceMetadata(
+                resource="https://example.com/vgi",
+                authorization_servers=("https://auth.example.com",),
+                client_id='bad"id',
+            )
+        with pytest.raises(ValueError, match="URL-safe"):
+            OAuthResourceMetadata(
+                resource="https://example.com/vgi",
+                authorization_servers=("https://auth.example.com",),
+                client_id="has space",
+            )
+
+    def test_client_id_in_well_known_json(self) -> None:
+        """client_id appears in well-known JSON when set."""
+        server = RpcServer(_EchoService, _EchoImpl())
+        client = make_sync_client(server, signing_key=b"k", oauth_resource_metadata=_METADATA_WITH_CLIENT_ID)
+        resp = client.get("/.well-known/oauth-protected-resource")
+        body = json.loads(resp.content)
+        assert body["client_id"] == "my-client-id"
+
+    def test_client_id_in_www_authenticate(self) -> None:
+        """client_id appears in WWW-Authenticate header when metadata has client_id."""
+        _priv, pub = _make_rsa_key()
+        auth_fn = _make_local_auth(pub)
+        server = RpcServer(_EchoService, _EchoImpl())
+        client = make_sync_client(
+            server,
+            signing_key=b"k",
+            authenticate=auth_fn,
+            oauth_resource_metadata=_METADATA_WITH_CLIENT_ID,
+        )
+        resp = client.post(
+            "/vgi/echo",
+            content=b"garbage",
+            headers={"Content-Type": "application/octet-stream"},
+        )
+        assert resp.status_code == 401
+        www_auth = resp.headers.get("www-authenticate", "")
+        assert 'client_id="my-client-id"' in www_auth
+
+    def test_client_id_absent_from_www_authenticate(self) -> None:
+        """client_id absent from WWW-Authenticate when metadata has no client_id."""
+        _priv, pub = _make_rsa_key()
+        auth_fn = _make_local_auth(pub)
+        server = RpcServer(_EchoService, _EchoImpl())
+        client = make_sync_client(
+            server,
+            signing_key=b"k",
+            authenticate=auth_fn,
+            oauth_resource_metadata=_METADATA,
+        )
+        resp = client.post(
+            "/vgi/echo",
+            content=b"garbage",
+            headers={"Content-Type": "application/octet-stream"},
+        )
+        assert resp.status_code == 401
+        www_auth = resp.headers.get("www-authenticate", "")
+        assert "client_id" not in www_auth
+
+    def test_parse_client_id_extracts_value(self) -> None:
+        """parse_client_id() extracts value from header."""
+        header = (
+            'Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource/vgi"'
+            ', client_id="my-app"'
+        )
+        assert parse_client_id(header) == "my-app"
+
+    def test_parse_client_id_returns_none_when_absent(self) -> None:
+        """parse_client_id() returns None when not present."""
+        assert parse_client_id("Bearer") is None
+        assert parse_client_id('Bearer resource_metadata="https://example.com"') is None
+        assert parse_client_id("") is None
+
+    def test_client_discovery_round_trip_with_client_id(self) -> None:
+        """Client discovers client_id set on server."""
+        server = RpcServer(_EchoService, _EchoImpl())
+        client = make_sync_client(server, signing_key=b"k", oauth_resource_metadata=_METADATA_WITH_CLIENT_ID)
+        meta = http_oauth_metadata(client=client)
+        assert meta is not None
+        assert meta.client_id == "my-client-id"
+
     def test_401_discovery_flow(self) -> None:
         """Full 401-based discovery: get 401, parse header, fetch metadata."""
         _priv, pub = _make_rsa_key()

uv.lock

@@ -36,6 +36,7 @@
     http_connect,
     http_introspect,
     http_oauth_metadata,
+    parse_client_id,
     parse_resource_metadata_url,
     request_upload_urls,
 )
@@ -89,6 +90,7 @@
     "http_introspect",
     "http_oauth_metadata",
     "make_sync_client",
+    "parse_client_id",
     "parse_resource_metadata_url",
     "make_wsgi_app",
     "serve_http",

vgi_rpc/http/__init__.py

@@ -948,6 +948,8 @@ class OAuthResourceMetadataResponse:
         resource_documentation: URL to developer documentation.
         resource_policy_uri: URL to the resource's privacy policy.
         resource_tos_uri: URL to the resource's terms of service.
+        client_id: OAuth client_id to use when authenticating with the
+            authorization server.  Custom extension (not in RFC 9728).
 
     """
 
@@ -960,6 +962,7 @@ class OAuthResourceMetadataResponse:
     resource_documentation: str | None = None
     resource_policy_uri: str | None = None
     resource_tos_uri: str | None = None
+    client_id: str | None = None
 
 
 def http_oauth_metadata(
@@ -1011,6 +1014,7 @@ def http_oauth_metadata(
 
 
 _RESOURCE_METADATA_RE = re.compile(r'resource_metadata="([^"]+)"')
+_CLIENT_ID_RE = re.compile(r'client_id="([^"]+)"')
 
 
 def parse_resource_metadata_url(www_authenticate: str) -> str | None:
@@ -1032,6 +1036,24 @@ def parse_resource_metadata_url(www_authenticate: str) -> str | None:
     return match.group(1) if match else None
 
 
+def parse_client_id(www_authenticate: str) -> str | None:
+    """Extract the ``client_id`` from a ``WWW-Authenticate`` header.
+
+    Parses a ``Bearer`` challenge and returns the ``client_id`` parameter
+    value, or ``None`` if not present.  This is a custom extension (not
+    defined in RFC 9728).
+
+    Args:
+        www_authenticate: The ``WWW-Authenticate`` header value.
+
+    Returns:
+        The client_id string, or ``None`` if not present.
+
+    """
+    match = _CLIENT_ID_RE.search(www_authenticate)
+    return match.group(1) if match else None
+
+
 def _parse_metadata_json(body: dict[str, Any]) -> OAuthResourceMetadataResponse:
     """Parse a JSON dict into an ``OAuthResourceMetadataResponse``.
 
@@ -1055,6 +1077,7 @@ def _parse_metadata_json(body: dict[str, Any]) -> OAuthResourceMetadataResponse:
         resource_documentation=body.get("resource_documentation"),
         resource_policy_uri=body.get("resource_policy_uri"),
         resource_tos_uri=body.get("resource_tos_uri"),
+        client_id=body.get("client_id"),
     )
 
 

vgi_rpc/http/_client.py

@@ -13,11 +13,14 @@
 from __future__ import annotations
 
 import json
+import re
 from dataclasses import dataclass
 from urllib.parse import urlparse
 
 import falcon
 
+_URL_SAFE_RE = re.compile(r"[A-Za-z0-9\-._~]+")
+
 
 @dataclass(frozen=True)
 class OAuthResourceMetadata:
@@ -39,6 +42,9 @@ class OAuthResourceMetadata:
         resource_documentation: URL to developer documentation.
         resource_policy_uri: URL to the resource's privacy policy.
         resource_tos_uri: URL to the resource's terms of service.
+        client_id: OAuth client_id that clients should use when
+            authenticating with the authorization server.  Custom
+            extension (not defined in RFC 9728).
 
     Raises:
         ValueError: If *resource* is empty or *authorization_servers* is empty.
@@ -54,13 +60,19 @@ class OAuthResourceMetadata:
     resource_documentation: str | None = None
     resource_policy_uri: str | None = None
     resource_tos_uri: str | None = None
+    client_id: str | None = None
 
     def __post_init__(self) -> None:
         """Validate required fields."""
         if not self.resource:
             raise ValueError("OAuthResourceMetadata.resource must not be empty")
         if not self.authorization_servers:
             raise ValueError("OAuthResourceMetadata.authorization_servers must contain at least one entry")
+        if self.client_id is not None and not _URL_SAFE_RE.fullmatch(self.client_id):
+            raise ValueError(
+                "OAuthResourceMetadata.client_id must contain only URL-safe characters "
+                "(alphanumeric, hyphen, underscore, period, tilde)"
+            )
 
     def to_json_dict(self) -> dict[str, object]:
         """Serialize to a JSON-compatible dict per RFC 9728.
@@ -89,6 +101,8 @@ def to_json_dict(self) -> dict[str, object]:
             d["resource_policy_uri"] = self.resource_policy_uri
         if self.resource_tos_uri is not None:
             d["resource_tos_uri"] = self.resource_tos_uri
+        if self.client_id is not None:
+            d["client_id"] = self.client_id
         return d
 
 
@@ -132,4 +146,7 @@ def _build_www_authenticate(metadata: OAuthResourceMetadata, prefix: str = "/vgi
     parsed = urlparse(metadata.resource)
     path_suffix = prefix if prefix != "/" else ""
     well_known_url = f"{parsed.scheme}://{parsed.netloc}/.well-known/oauth-protected-resource{path_suffix}"
-    return f'Bearer resource_metadata="{well_known_url}"'
+    challenge = f'Bearer resource_metadata="{well_known_url}"'
+    if metadata.client_id is not None:
+        challenge += f', client_id="{metadata.client_id}"'
+    return challenge