Resolve the MCP signing key

Three loose ends from the design's signing-key step.

The derived signing and storage keys are only as strong as the client
secret they come from, and nothing checked it. The service now refuses
to start below 32 characters. Identity providers issue well above that;
the check exists to reject a hand-written placeholder. The deployment
guide already told operators the service enforced this -- it did not.

derive_jwt_key was imported from fastmcp.server.auth.jwt_issuer, a
private symbol with no deprecation contract: a minor release could drop
it, or change its derivation and silently invalidate every stored
registration and token. The derivation is now local, with the same HKDF
parameters, so the bytes are identical and existing state stays
readable. test_auth asserts that equivalence against FastMCP directly,
so a change on their side surfaces as a failure rather than as
undecryptable Redis state.

The production-readiness warning said the chart exposes no alternative
to the derived key and told operators to assess the limitation before
rolling out. That framing does not survive reading FastMCP 3.4.7:
high-entropy material goes through HKDF, and the PBKDF2 path with a
length warning is reserved for low-entropy operator strings. The
warning is replaced with the entropy requirement the design states.

Author: jiaenren

docs/deployment_guide/advanced_config/mcp.rst

@@ -147,16 +147,13 @@ sessions and makes old encrypted state, including DCR registrations, unusable.
 Users must authenticate again, and DCR clients might need to remove and re-add
 the MCP entry before login.
 
-.. warning::
-
-   OSMO currently relies on FastMCP's default derived signing key to avoid a
-   second operator-managed secret. FastMCP documents that default as a
-   development or local-testing convenience and recommends an explicit
-   independent signing key for production. The current OSMO chart does not
-   expose that independent-key option. Assess this limitation before a
-   production rollout and require a high-entropy upstream client secret. See
-   the `FastMCP OIDC proxy signing-key guidance
-   <https://gofastmcp.com/servers/auth/oidc-proxy#param-jwt-signing-key>`_.
+Because both keys come from the client secret, the strength they provide is the
+strength of that secret. FastMCP passes it through HKDF as high-entropy key
+material, a path distinct from the password-based derivation it reserves for
+low-entropy operator-supplied strings. The service therefore requires a client
+secret of at least 32 characters and refuses to start below it. Identity
+providers issue secrets well above that length; the check exists to reject a
+hand-written placeholder.
 
 Configure Helm Values
 ---------------------

src/service/mcp/auth.py

@@ -16,12 +16,14 @@
 SPDX-License-Identifier: Apache-2.0
 """
 
+import base64
 import dataclasses
 from typing import cast
 from urllib import parse
 
 from cryptography.fernet import Fernet
-from fastmcp.server.auth.jwt_issuer import derive_jwt_key
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
 from fastmcp.server.auth.oidc_proxy import OIDCProxy
 from fastmcp.server.auth.providers.jwt import JWTVerifier
 from key_value.aio.protocols import AsyncKeyValue
@@ -78,6 +80,11 @@ def get_token_verifier(  # pylint: disable=unused-argument
             audience=self._access_token_audience,
             required_scopes=required_scopes,
         )
+# The derived signing and storage keys are only as strong as the secret
+# they come from. Identity providers issue well above this; the check
+# exists to reject a hand-written placeholder.
+_MIN_CLIENT_SECRET_LENGTH = 32
+
 _REQUIRED_WHEN_AUTH_ENABLED = (
     'resource_url',
     'redis_url',
@@ -223,6 +230,13 @@ def create_auth_runtime(config: MCPAuthConfig) -> MCPAuthRuntime:
         cast(str, config.oidc_client_secret_file),
         'OIDC client secret',
     )
+    if len(client_secret) < _MIN_CLIENT_SECRET_LENGTH:
+        raise ValueError(
+            'OIDC client secret must be at least '
+            f'{_MIN_CLIENT_SECRET_LENGTH} characters: both the proxy token '
+            'signing key and the Redis storage key are derived from it, so '
+            'its entropy is their entropy'
+        )
     redis_client = redis_asyncio.Redis.from_url(
         cast(str, config.redis_url),
         password=_read_optional_secret(config.redis_password_file),
@@ -281,14 +295,32 @@ def create_auth_runtime(config: MCPAuthConfig) -> MCPAuthRuntime:
     return MCPAuthRuntime(provider, redis_client)
 
 
+def _derive_fernet_key(material: str, *, salt: str) -> bytes:
+    """Derive a Fernet key from high-entropy material.
+
+    Reproduces FastMCP's own derivation with the same HKDF parameters rather
+    than importing ``fastmcp.server.auth.jwt_issuer.derive_jwt_key``, which is
+    private and carries no deprecation contract. The bytes are identical, so
+    state encrypted before this change stays readable; ``test_auth`` asserts
+    that equivalence against FastMCP directly.
+    """
+    derived = HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=salt.encode(),
+        info=b'Fernet',
+    ).derive(material.encode())
+    return base64.urlsafe_b64encode(derived)
+
+
 def _storage_encryption_key(client_secret: str) -> bytes:
     """Mirror FastMCP's default signing and storage key derivation."""
-    signing_key = derive_jwt_key(
-        high_entropy_material=client_secret,
+    signing_key = _derive_fernet_key(
+        client_secret,
         salt='fastmcp-jwt-signing-key',
     )
-    return derive_jwt_key(
-        high_entropy_material=signing_key.decode('ascii'),
+    return _derive_fernet_key(
+        signing_key.decode('ascii'),
         salt='fastmcp-storage-encryption-key',
     )
 

src/service/mcp/tests/test_auth.py

@@ -22,6 +22,7 @@
 import unittest
 from unittest import mock
 
+from fastmcp.server.auth.jwt_issuer import derive_jwt_key
 from fastmcp.server.auth.oidc_proxy import OIDCConfiguration, OIDCProxy
 from fastmcp.server.auth.providers.jwt import JWTVerifier
 from fastmcp.server.auth.oauth_proxy.models import UpstreamTokenSet
@@ -31,6 +32,10 @@
 
 from src.service.mcp import auth, server
 
+# Long enough to satisfy the client-secret entropy check; identity
+# providers issue secrets of this order.
+_TEST_CLIENT_SECRET = 'client-secret-0123456789abcdef0123456789'
+
 
 class MCPAuthConfigTest(unittest.TestCase):
     def test_authentication_is_not_optional(self) -> None:
@@ -97,7 +102,7 @@ async def test_issuer_falls_back_to_the_discovery_document(self) -> None:
         Only an Entra v1 resource application needs it configured, so a
         deployment whose discovery issuer is the real one supplies nothing.
         """
-        with _secret_file('client-secret') as client_secret_file:
+        with _secret_file(_TEST_CLIENT_SECRET) as client_secret_file:
             config = _config(
                 oidc_client_secret_file=client_secret_file,
                 oidc_access_token_issuer=None,
@@ -152,7 +157,7 @@ async def test_issuer_falls_back_to_the_discovery_document(self) -> None:
                 )
 
     async def test_factory_uses_plain_oidc_proxy_and_split_scope_contract(self) -> None:
-        with _secret_file('client-secret') as client_secret_file:
+        with _secret_file(_TEST_CLIENT_SECRET) as client_secret_file:
             config = _config(
                 oidc_client_secret_file=client_secret_file,
             )
@@ -208,8 +213,8 @@ async def test_factory_uses_plain_oidc_proxy_and_split_scope_contract(self) -> N
                 self.assertIsInstance(provider, OIDCProxy)
                 self.assertEqual(
                     provider._jwt_signing_key,  # pylint: disable=protected-access
-                    auth.derive_jwt_key(
-                        high_entropy_material='client-secret',
+                    derive_jwt_key(
+                        high_entropy_material=_TEST_CLIENT_SECRET,
                         salt='fastmcp-jwt-signing-key',
                     ),
                 )
@@ -384,6 +389,14 @@ async def __aexit__(self, *args: object) -> None:
                 await runtime.aclose()
             redis_client.aclose.assert_awaited_once()
 
+    def test_short_client_secret_fails_at_startup(self) -> None:
+        """The derived keys are only as strong as the secret behind them."""
+        with _secret_file('too-short') as client_secret_file:
+            config = _config(oidc_client_secret_file=client_secret_file)
+            with self.assertRaises(ValueError) as caught:
+                auth.create_auth_runtime(config)
+        self.assertIn('at least 32 characters', str(caught.exception))
+
     def test_storage_key_matches_fastmcp_default_and_is_deterministic(self) -> None:
         first = auth._storage_encryption_key(  # pylint: disable=protected-access
             'client-secret',
@@ -394,11 +407,11 @@ def test_storage_key_matches_fastmcp_default_and_is_deterministic(self) -> None:
         different = auth._storage_encryption_key(  # pylint: disable=protected-access
             'rotated-client-secret',
         )
-        signing_key = auth.derive_jwt_key(
+        signing_key = derive_jwt_key(
             high_entropy_material='client-secret',
             salt='fastmcp-jwt-signing-key',
         )
-        expected = auth.derive_jwt_key(
+        expected = derive_jwt_key(
             high_entropy_material=signing_key.decode('ascii'),
             salt='fastmcp-storage-encryption-key',
         )