Add client_secret to OAuth Resource Metadata and reduce cache max-age to 60s

Google requires client_secret in OAuth resource metadata even when using PKCE.
Added following the same pattern as client_id. Reduced .well-known cache
max-age from 3600 to 60 seconds. Bump version to 0.1.20.

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="..."` (and optionally `client_id="..."`)
+2. 401 responses include `WWW-Authenticate: Bearer resource_metadata="..."` (and optionally `client_id="..."`, `client_secret="..."`)
 3. Client fetches metadata to discover authorization server(s)
 4. Client authenticates with the AS and sends Bearer token
 
@@ -57,21 +57,23 @@ 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, parse_client_id, fetch_oauth_metadata
+from vgi_rpc.http import parse_resource_metadata_url, parse_client_id, parse_client_secret, fetch_oauth_metadata
 
 # 1. Make a request that returns 401
 resp = client.post("/vgi/my_method", ...)
 
-# 2. Parse the metadata URL and optional client_id from WWW-Authenticate header
+# 2. Parse the metadata URL, optional client_id and client_secret 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
+client_secret = parse_client_secret(www_auth)  # e.g. "my-secret" 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
+print(meta.client_secret)  # also available from the metadata document
 ```
 
 ## OAuthResourceMetadata
@@ -91,6 +93,7 @@ Pass to `make_wsgi_app(oauth_resource_metadata=...)` to enable OAuth discovery.
 | `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)* |
+| `client_secret` | `str \| None` | No | OAuth client_secret for auth server *(custom extension, not in RFC 9728)*. Intended for public/PKCE clients (e.g. Google OAuth) where the secret is not truly confidential. |
 
 Raises `ValueError` if `resource` is empty or `authorization_servers` is empty.
 
@@ -287,18 +290,31 @@ client_id = parse_client_id('Bearer resource_metadata="https://...", client_id="
 
 Returns `None` if the header doesn't contain `client_id`.
 
+## parse_client_secret()
+
+Extract the `client_secret` from a `WWW-Authenticate` header. Custom extension (not in RFC 9728).
+
+```python
+from vgi_rpc.http import parse_client_secret
+
+client_secret = parse_client_secret('Bearer resource_metadata="https://...", client_secret="my-secret"')
+# "my-secret"
+```
+
+Returns `None` if the header doesn't contain `client_secret`.
+
 ## OAuthResourceMetadataResponse
 
 Frozen dataclass returned by `http_oauth_metadata()` and `fetch_oauth_metadata()`.
-Same fields as `OAuthResourceMetadata` (the server-side config class), including `client_id`.
+Same fields as `OAuthResourceMetadata` (the server-side config class), including `client_id` and `client_secret`.
 
 ## 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
+- **Custom extensions**: `client_id` and `client_secret` fields on `OAuthResourceMetadata` / `OAuthResourceMetadataResponse` and in `WWW-Authenticate` headers are not defined in RFC 9728
 
 ## Installation
 

pyproject.toml

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

tests/test_oauth.py

@@ -26,6 +26,7 @@
     jwt_authenticate,
     make_sync_client,
     parse_client_id,
+    parse_client_secret,
     parse_resource_metadata_url,
 )
 
@@ -123,6 +124,9 @@ def authenticate(req: falcon.Request) -> AuthContext:
 )
 
 _METADATA_WITH_CLIENT_ID = dataclasses.replace(_METADATA, client_id="my-client-id")
+_METADATA_WITH_CLIENT_SECRET = dataclasses.replace(
+    _METADATA, client_id="my-client-id", client_secret="my-client-secret"
+)
 
 
 # ---------------------------------------------------------------------------
@@ -188,6 +192,7 @@ def test_well_known_omits_default_fields(self) -> None:
         assert "bearer_methods_supported" not in d
         assert "resource_name" not in d
         assert "client_id" not in d
+        assert "client_secret" not in d
 
     def test_well_known_exempt_from_auth(self) -> None:
         """Well-known endpoint is accessible even with auth enabled."""
@@ -271,7 +276,7 @@ def test_cache_control_header(self) -> None:
         resp = client.get("/.well-known/oauth-protected-resource")
         assert resp.status_code == 200
         cache = resp.headers.get("cache-control", "")
-        assert "max-age" in cache
+        assert "max-age=60" in cache
 
     def test_backwards_compatible(self) -> None:
         """Server without oauth_resource_metadata still works normally."""
@@ -377,6 +382,91 @@ def test_client_discovery_round_trip_with_client_id(self) -> None:
         assert meta is not None
         assert meta.client_id == "my-client-id"
 
+    def test_client_secret_rejects_unsafe_characters(self) -> None:
+        """client_secret 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_secret='bad"secret',
+            )
+        with pytest.raises(ValueError, match="URL-safe"):
+            OAuthResourceMetadata(
+                resource="https://example.com/vgi",
+                authorization_servers=("https://auth.example.com",),
+                client_secret="has space",
+            )
+
+    def test_client_secret_in_well_known_json(self) -> None:
+        """client_secret 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_SECRET)
+        resp = client.get("/.well-known/oauth-protected-resource")
+        body = json.loads(resp.content)
+        assert body["client_secret"] == "my-client-secret"
+
+    def test_client_secret_in_www_authenticate(self) -> None:
+        """client_secret appears in WWW-Authenticate header when metadata has client_secret."""
+        _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_SECRET,
+        )
+        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_secret="my-client-secret"' in www_auth
+
+    def test_client_secret_absent_from_www_authenticate(self) -> None:
+        """client_secret absent from WWW-Authenticate when metadata has no client_secret."""
+        _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_secret" not in www_auth
+
+    def test_parse_client_secret_extracts_value(self) -> None:
+        """parse_client_secret() extracts value from header."""
+        header = (
+            'Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource/vgi"'
+            ', client_id="my-app", client_secret="my-secret"'
+        )
+        assert parse_client_secret(header) == "my-secret"
+
+    def test_parse_client_secret_returns_none_when_absent(self) -> None:
+        """parse_client_secret() returns None when not present."""
+        assert parse_client_secret("Bearer") is None
+        assert parse_client_secret('Bearer resource_metadata="https://example.com"') is None
+        assert parse_client_secret("") is None
+
+    def test_client_discovery_round_trip_with_client_secret(self) -> None:
+        """Client discovers client_secret set on server."""
+        server = RpcServer(_EchoService, _EchoImpl())
+        client = make_sync_client(server, signing_key=b"k", oauth_resource_metadata=_METADATA_WITH_CLIENT_SECRET)
+        meta = http_oauth_metadata(client=client)
+        assert meta is not None
+        assert meta.client_secret == "my-client-secret"
+
     def test_401_discovery_flow(self) -> None:
         """Full 401-based discovery: get 401, parse header, fetch metadata."""
         _priv, pub = _make_rsa_key()

uv.lock

@@ -37,6 +37,7 @@
     http_introspect,
     http_oauth_metadata,
     parse_client_id,
+    parse_client_secret,
     parse_resource_metadata_url,
     request_upload_urls,
 )
@@ -91,6 +92,7 @@
     "http_oauth_metadata",
     "make_sync_client",
     "parse_client_id",
+    "parse_client_secret",
     "parse_resource_metadata_url",
     "make_wsgi_app",
     "serve_http",

vgi_rpc/http/__init__.py

@@ -950,6 +950,8 @@ class OAuthResourceMetadataResponse:
         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).
+        client_secret: OAuth client_secret to use when authenticating with the
+            authorization server.  Custom extension (not in RFC 9728).
 
     """
 
@@ -963,6 +965,7 @@ class OAuthResourceMetadataResponse:
     resource_policy_uri: str | None = None
     resource_tos_uri: str | None = None
     client_id: str | None = None
+    client_secret: str | None = None
 
 
 def http_oauth_metadata(
@@ -1015,6 +1018,7 @@ def http_oauth_metadata(
 
 _RESOURCE_METADATA_RE = re.compile(r'resource_metadata="([^"]+)"')
 _CLIENT_ID_RE = re.compile(r'client_id="([^"]+)"')
+_CLIENT_SECRET_RE = re.compile(r'client_secret="([^"]+)"')
 
 
 def parse_resource_metadata_url(www_authenticate: str) -> str | None:
@@ -1054,6 +1058,24 @@ def parse_client_id(www_authenticate: str) -> str | None:
     return match.group(1) if match else None
 
 
+def parse_client_secret(www_authenticate: str) -> str | None:
+    """Extract the ``client_secret`` from a ``WWW-Authenticate`` header.
+
+    Parses a ``Bearer`` challenge and returns the ``client_secret`` 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_secret string, or ``None`` if not present.
+
+    """
+    match = _CLIENT_SECRET_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``.
 
@@ -1078,6 +1100,7 @@ def _parse_metadata_json(body: dict[str, Any]) -> OAuthResourceMetadataResponse:
         resource_policy_uri=body.get("resource_policy_uri"),
         resource_tos_uri=body.get("resource_tos_uri"),
         client_id=body.get("client_id"),
+        client_secret=body.get("client_secret"),
     )
 
 

vgi_rpc/http/_client.py

@@ -45,6 +45,9 @@ class OAuthResourceMetadata:
         client_id: OAuth client_id that clients should use when
             authenticating with the authorization server.  Custom
             extension (not defined in RFC 9728).
+        client_secret: OAuth client_secret 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.
@@ -61,6 +64,7 @@ class OAuthResourceMetadata:
     resource_policy_uri: str | None = None
     resource_tos_uri: str | None = None
     client_id: str | None = None
+    client_secret: str | None = None
 
     def __post_init__(self) -> None:
         """Validate required fields."""
@@ -73,6 +77,11 @@ def __post_init__(self) -> None:
                 "OAuthResourceMetadata.client_id must contain only URL-safe characters "
                 "(alphanumeric, hyphen, underscore, period, tilde)"
             )
+        if self.client_secret is not None and not _URL_SAFE_RE.fullmatch(self.client_secret):
+            raise ValueError(
+                "OAuthResourceMetadata.client_secret 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.
@@ -103,6 +112,8 @@ def to_json_dict(self) -> dict[str, object]:
             d["resource_tos_uri"] = self.resource_tos_uri
         if self.client_id is not None:
             d["client_id"] = self.client_id
+        if self.client_secret is not None:
+            d["client_secret"] = self.client_secret
         return d
 
 
@@ -124,7 +135,7 @@ def on_get(self, req: falcon.Request, resp: falcon.Response) -> None:
         """
         resp.content_type = falcon.MEDIA_JSON
         resp.data = self._body
-        resp.set_header("Cache-Control", "public, max-age=3600")
+        resp.set_header("Cache-Control", "public, max-age=60")
 
 
 def _build_www_authenticate(metadata: OAuthResourceMetadata, prefix: str = "/vgi") -> str:
@@ -149,4 +160,8 @@ def _build_www_authenticate(metadata: OAuthResourceMetadata, prefix: str = "/vgi
     challenge = f'Bearer resource_metadata="{well_known_url}"'
     if metadata.client_id is not None:
         challenge += f', client_id="{metadata.client_id}"'
+    # client_secret in the header is intentional: Google's PKCE flow treats it
+    # as a "public" secret for native/SPA apps, not a truly confidential value.
+    if metadata.client_secret is not None:
+        challenge += f', client_secret="{metadata.client_secret}"'
     return challenge