From ed57dd854a5a609cd376884de8055644851187ae Mon Sep 17 00:00:00 2001 From: James Maes Date: Thu, 5 Nov 2026 05:28:01 -0600 Subject: [PATCH] feat(security): authenticate MCP HTTP requests and enforce table access Add a bearer-token authentication filter and an HTTP-principal session provider so MCP requests run as the authenticated principal, and gate the table list/schema tools and resources through a shared TableAccess check. Add McpHttpSecurityTest and adapt the existing test utilities. Build against the published QQQ 4.1 BOM (4.1.0-RC.21), add the servlet API (provided) and the test-scope Javalin/RDBMS/Postgres/H2/Testcontainers dependencies the security test needs, and run surefire under UTC. Co-Authored-By: Claude Sonnet 5.5 --- pom.xml | 53 +- .../qbits/middlewaremcp/TableAccess.java | 91 ++++ .../resources/TableListResourceHandler.java | 7 + .../resources/TableSchemaResourceHandler.java | 3 +- .../HttpPrincipalMCPSessionProvider.java | 60 +++ .../tools/ListTablesToolHandler.java | 7 + .../tools/TableSchemaToolHandler.java | 7 +- .../McpBearerAuthenticationFilter.java | 158 ++++++ .../middlewaremcp/McpHttpSecurityTest.java | 455 ++++++++++++++++++ .../qbits/middlewaremcp/TestUtils.java | 2 +- .../tools/RunProcessToolHandlerTest.java | 2 +- 11 files changed, 838 insertions(+), 7 deletions(-) create mode 100644 src/main/java/com/kingsrook/qbits/middlewaremcp/TableAccess.java create mode 100644 src/main/java/com/kingsrook/qbits/middlewaremcp/session/HttpPrincipalMCPSessionProvider.java create mode 100644 src/main/java/com/kingsrook/qbits/middlewaremcp/transport/McpBearerAuthenticationFilter.java create mode 100644 src/test/java/com/kingsrook/qbits/middlewaremcp/McpHttpSecurityTest.java diff --git a/pom.xml b/pom.xml index 36ed71b..6650ff3 100644 --- a/pom.xml +++ b/pom.xml @@ -66,6 +66,9 @@ 0.1.0-SNAPSHOT 0.12.0 + 21 + + @@ -73,7 +76,9 @@ com.kingsrook.qqq qqq-bom-pom - 0.40.0 + + 4.1.0-RC.21 pom import @@ -97,7 +102,14 @@ com.fasterxml.jackson.core jackson-databind - 2.14.0 + + + + + jakarta.servlet + jakarta.servlet-api + 6.0.0 + provided @@ -108,13 +120,48 @@ org.assertj assertj-core - 3.27.3 + 3.27.7 + test + + + com.kingsrook.qqq + qqq-middleware-javalin + test + + + com.kingsrook.qqq + qqq-backend-module-rdbms + test + + + com.kingsrook.qqq + qqq-backend-module-postgres + test + + + com.h2database + h2 + 2.2.220 + test + + + org.testcontainers + testcontainers + 2.0.3 test + + + org.apache.maven.plugins + maven-surefire-plugin + + @{argLine} -Duser.timezone=UTC + + org.jacoco jacoco-maven-plugin diff --git a/src/main/java/com/kingsrook/qbits/middlewaremcp/TableAccess.java b/src/main/java/com/kingsrook/qbits/middlewaremcp/TableAccess.java new file mode 100644 index 0000000..d2fbf35 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/middlewaremcp/TableAccess.java @@ -0,0 +1,91 @@ +/* + * QQQ - Low-code Application Framework for Engineers. + * Copyright (C) 2021-2024. Kingsrook, LLC + * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States + * contact@kingsrook.com + * https://github.com/Kingsrook/ + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.kingsrook.qbits.middlewaremcp; + + +import java.util.Set; +import com.kingsrook.qbits.middlewaremcp.model.MCPTableMetaData; +import com.kingsrook.qqq.backend.core.actions.metadata.MetaDataAction; +import com.kingsrook.qqq.backend.core.exceptions.QException; +import com.kingsrook.qqq.backend.core.model.actions.metadata.MetaDataInput; +import com.kingsrook.qqq.backend.core.model.metadata.QInstance; +import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData; + + +/******************************************************************************* + ** Which tables the CURRENT session may even learn about through MCP. A table is + ** discoverable only if the server exposes it (allow list, not hidden, not + ** excluded) AND the session's own permissions let it see the table (the same + ** decision the application's metadata makes for that session), so listing and + ** describing never disclose a table the caller could not open. Must be called + ** with the caller's QContext in place. + *******************************************************************************/ +public final class TableAccess +{ + /*************************************************************************** + ** Utility class. + ***************************************************************************/ + private TableAccess() + { + } + + + + /*************************************************************************** + ** The table names the current session may see, from the application's own + ** metadata for that session. + ***************************************************************************/ + public static Set visibleToSession() throws QException + { + return new MetaDataAction().execute(new MetaDataInput()).getTables().keySet(); + } + + + + /*************************************************************************** + ** Whether the table is exposed by this server (independent of the caller). + ***************************************************************************/ + public static boolean isExposed(QInstance qInstance, QMCPMetaData mcpMetaData, String tableName) + { + QTableMetaData table = qInstance.getTable(tableName); + if(table == null || Boolean.TRUE.equals(table.getIsHidden())) + { + return false; + } + Set exposed = mcpMetaData.getExposedTableNames(); + if(exposed != null && !exposed.contains(tableName)) + { + return false; + } + MCPTableMetaData supplemental = (MCPTableMetaData) table.getSupplementalMetaData(MCPTableMetaData.TYPE); + return supplemental == null || !supplemental.isExcluded(); + } + + + + /*************************************************************************** + ** Exposed by this server and visible to the current session. + ***************************************************************************/ + public static boolean isDiscoverable(QInstance qInstance, QMCPMetaData mcpMetaData, String tableName) throws QException + { + return isExposed(qInstance, mcpMetaData, tableName) && visibleToSession().contains(tableName); + } +} diff --git a/src/main/java/com/kingsrook/qbits/middlewaremcp/resources/TableListResourceHandler.java b/src/main/java/com/kingsrook/qbits/middlewaremcp/resources/TableListResourceHandler.java index b8d2a51..f10e4c1 100644 --- a/src/main/java/com/kingsrook/qbits/middlewaremcp/resources/TableListResourceHandler.java +++ b/src/main/java/com/kingsrook/qbits/middlewaremcp/resources/TableListResourceHandler.java @@ -33,6 +33,7 @@ import com.kingsrook.qqq.backend.core.logging.QLogger; import com.kingsrook.qqq.backend.core.model.metadata.QInstance; import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData; import com.kingsrook.qbits.middlewaremcp.QMCPMetaData; +import com.kingsrook.qbits.middlewaremcp.TableAccess; import com.kingsrook.qbits.middlewaremcp.model.MCPTableMetaData; import com.kingsrook.qbits.middlewaremcp.session.MCPSessionProviderInterface; import io.modelcontextprotocol.server.McpSyncServerExchange; @@ -77,6 +78,7 @@ public class TableListResourceHandler try { Set exposedTableNames = mcpMetaData.getExposedTableNames(); + Set visible = TableAccess.visibleToSession(); List> tables = new ArrayList<>(); for(Map.Entry entry : qInstance.getTables().entrySet()) @@ -84,6 +86,11 @@ public class TableListResourceHandler String tableName = entry.getKey(); QTableMetaData table = entry.getValue(); + if(!visible.contains(tableName)) + { + continue; + } + if(Boolean.TRUE.equals(table.getIsHidden())) { continue; diff --git a/src/main/java/com/kingsrook/qbits/middlewaremcp/resources/TableSchemaResourceHandler.java b/src/main/java/com/kingsrook/qbits/middlewaremcp/resources/TableSchemaResourceHandler.java index 09c381b..7c2b8ca 100644 --- a/src/main/java/com/kingsrook/qbits/middlewaremcp/resources/TableSchemaResourceHandler.java +++ b/src/main/java/com/kingsrook/qbits/middlewaremcp/resources/TableSchemaResourceHandler.java @@ -34,6 +34,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.QInstance; import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData; import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData; import com.kingsrook.qbits.middlewaremcp.QMCPMetaData; +import com.kingsrook.qbits.middlewaremcp.TableAccess; import com.kingsrook.qbits.middlewaremcp.model.MCPTableMetaData; import com.kingsrook.qbits.middlewaremcp.session.MCPSessionProviderInterface; import io.modelcontextprotocol.server.McpSyncServerExchange; @@ -88,7 +89,7 @@ public class TableSchemaResourceHandler QContext.init(qInstance, sessionProvider.createSession(exchange)); try { - QTableMetaData table = qInstance.getTable(tableName); + QTableMetaData table = TableAccess.isDiscoverable(qInstance, mcpMetaData, tableName) ? qInstance.getTable(tableName) : null; if(table == null) { String errorJson = "{\"error\": \"Table not found: " + tableName + "\"}"; diff --git a/src/main/java/com/kingsrook/qbits/middlewaremcp/session/HttpPrincipalMCPSessionProvider.java b/src/main/java/com/kingsrook/qbits/middlewaremcp/session/HttpPrincipalMCPSessionProvider.java new file mode 100644 index 0000000..a500620 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/middlewaremcp/session/HttpPrincipalMCPSessionProvider.java @@ -0,0 +1,60 @@ +/* + * QQQ - Low-code Application Framework for Engineers. + * Copyright (C) 2021-2024. Kingsrook, LLC + * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States + * contact@kingsrook.com + * https://github.com/Kingsrook/ + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.kingsrook.qbits.middlewaremcp.session; + + +import com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException; +import com.kingsrook.qqq.backend.core.exceptions.QException; +import com.kingsrook.qqq.backend.core.model.session.QSession; +import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession; +import io.modelcontextprotocol.common.McpTransportContext; +import io.modelcontextprotocol.server.McpSyncServerExchange; + + +/******************************************************************************* + ** The session of an MCP call is the QQQ session the caller authenticated as on + ** THIS HTTP request (see {@link com.kingsrook.qbits.middlewaremcp.transport.McpBearerAuthenticationFilter}), + ** never a server-wide identity: each call runs as exactly its own caller, under + ** that caller's permissions, security keys (tenant) and revocation state. A call + ** without an authenticated principal, or with a system session, is refused. + *******************************************************************************/ +public class HttpPrincipalMCPSessionProvider implements MCPSessionProviderInterface +{ + /** Key of the authenticated QSession in the per-request transport context. */ + public static final String CONTEXT_KEY = "com.kingsrook.qbits.middlewaremcp.session"; + + + + /*************************************************************************** + ** The calling principal's session, or a refusal. + ***************************************************************************/ + @Override + public QSession createSession(McpSyncServerExchange exchange) throws QException + { + McpTransportContext context = exchange == null ? null : exchange.transportContext(); + Object value = context == null ? null : context.get(CONTEXT_KEY); + if(!(value instanceof QSession session) || session instanceof QSystemUserSession || session.getUser() == null) + { + throw new QAuthenticationException("No authenticated principal for this MCP request"); + } + return session; + } +} diff --git a/src/main/java/com/kingsrook/qbits/middlewaremcp/tools/ListTablesToolHandler.java b/src/main/java/com/kingsrook/qbits/middlewaremcp/tools/ListTablesToolHandler.java index 1aa97c0..0030912 100644 --- a/src/main/java/com/kingsrook/qbits/middlewaremcp/tools/ListTablesToolHandler.java +++ b/src/main/java/com/kingsrook/qbits/middlewaremcp/tools/ListTablesToolHandler.java @@ -30,6 +30,7 @@ import com.kingsrook.qqq.backend.core.exceptions.QException; import com.kingsrook.qqq.backend.core.model.metadata.QInstance; import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData; import com.kingsrook.qbits.middlewaremcp.QMCPMetaData; +import com.kingsrook.qbits.middlewaremcp.TableAccess; import com.kingsrook.qbits.middlewaremcp.model.MCPTableMetaData; import com.kingsrook.qbits.middlewaremcp.session.MCPSessionProviderInterface; @@ -58,6 +59,7 @@ public class ListTablesToolHandler extends AbstractQQQToolHandler protected Object doExecute(Map arguments) throws QException { Set exposedTableNames = mcpMetaData.getExposedTableNames(); + Set visible = TableAccess.visibleToSession(); List> tables = new ArrayList<>(); for(Map.Entry entry : qInstance.getTables().entrySet()) @@ -65,6 +67,11 @@ public class ListTablesToolHandler extends AbstractQQQToolHandler String tableName = entry.getKey(); QTableMetaData table = entry.getValue(); + if(!visible.contains(tableName)) + { + continue; + } + // Skip hidden tables if(Boolean.TRUE.equals(table.getIsHidden())) { diff --git a/src/main/java/com/kingsrook/qbits/middlewaremcp/tools/TableSchemaToolHandler.java b/src/main/java/com/kingsrook/qbits/middlewaremcp/tools/TableSchemaToolHandler.java index a62087d..3275b6b 100644 --- a/src/main/java/com/kingsrook/qbits/middlewaremcp/tools/TableSchemaToolHandler.java +++ b/src/main/java/com/kingsrook/qbits/middlewaremcp/tools/TableSchemaToolHandler.java @@ -31,6 +31,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.QInstance; import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData; import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData; import com.kingsrook.qbits.middlewaremcp.QMCPMetaData; +import com.kingsrook.qbits.middlewaremcp.TableAccess; import com.kingsrook.qbits.middlewaremcp.model.MCPTableMetaData; import com.kingsrook.qbits.middlewaremcp.session.MCPSessionProviderInterface; @@ -64,7 +65,11 @@ public class TableSchemaToolHandler extends AbstractQQQToolHandler return Map.of("error", "tableName is required"); } - QTableMetaData table = qInstance.getTable(tableName); + //////////////////////////////////////////////////////////////////////////// + // a table that is not exposed, or that this caller cannot see, is reported // + // exactly like one that does not exist // + //////////////////////////////////////////////////////////////////////////// + QTableMetaData table = TableAccess.isDiscoverable(qInstance, mcpMetaData, tableName) ? qInstance.getTable(tableName) : null; if(table == null) { return Map.of("error", "Table not found: " + tableName); diff --git a/src/main/java/com/kingsrook/qbits/middlewaremcp/transport/McpBearerAuthenticationFilter.java b/src/main/java/com/kingsrook/qbits/middlewaremcp/transport/McpBearerAuthenticationFilter.java new file mode 100644 index 0000000..441c5d9 --- /dev/null +++ b/src/main/java/com/kingsrook/qbits/middlewaremcp/transport/McpBearerAuthenticationFilter.java @@ -0,0 +1,158 @@ +/* + * QQQ - Low-code Application Framework for Engineers. + * Copyright (C) 2021-2024. Kingsrook, LLC + * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States + * contact@kingsrook.com + * https://github.com/Kingsrook/ + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.kingsrook.qbits.middlewaremcp.transport; + + +import java.io.IOException; +import java.util.HashMap; +import java.util.Map; +import com.kingsrook.qbits.middlewaremcp.session.HttpPrincipalMCPSessionProvider; +import com.kingsrook.qqq.backend.core.context.QContext; +import com.kingsrook.qqq.backend.core.logging.QLogger; +import com.kingsrook.qqq.backend.core.model.metadata.QInstance; +import com.kingsrook.qqq.backend.core.model.session.QSession; +import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession; +import com.kingsrook.qqq.backend.core.modules.authentication.QAuthenticationModuleDispatcher; +import com.kingsrook.qqq.backend.core.modules.authentication.QAuthenticationModuleInterface; +import io.modelcontextprotocol.common.McpTransportContext; +import io.modelcontextprotocol.server.McpTransportContextExtractor; +import jakarta.servlet.Filter; +import jakarta.servlet.FilterChain; +import jakarta.servlet.ServletException; +import jakarta.servlet.ServletRequest; +import jakarta.servlet.ServletResponse; +import jakarta.servlet.http.HttpServletRequest; +import jakarta.servlet.http.HttpServletResponse; + + +/******************************************************************************* + ** Authenticates EVERY MCP HTTP request (initialize, list, read, call, notifications + ** and stream opens alike) with the application's own authentication module, from + ** an Authorization: Bearer token only: no cookies, API keys, basic + ** credentials or query parameters are accepted here. The resulting QSession is + ** carried to the tool handlers in the per-request transport context + ** ({@link #extractor()}), so the MCP server holds no identity of its own. A + ** request that cannot authenticate is answered 401 and never reaches the MCP + ** server; an MCP session id does not substitute for credentials, because the + ** token is checked again on every request. + *******************************************************************************/ +public class McpBearerAuthenticationFilter implements Filter +{ + private static final QLogger LOG = QLogger.getLogger(McpBearerAuthenticationFilter.class); + + private static final String REQUEST_ATTRIBUTE = McpBearerAuthenticationFilter.class.getName() + ".session"; + private static final String BEARER_PREFIX = "Bearer "; + + private final QInstance qInstance; + + + + /*************************************************************************** + ** Bind to the application whose authentication is used. Authentication + ** must exist and permissions must be enforced in core actions, otherwise + ** the tools would run unprotected. + ***************************************************************************/ + public McpBearerAuthenticationFilter(QInstance qInstance) + { + if(qInstance == null || qInstance.getAuthentication() == null) + { + throw new IllegalArgumentException("MCP over HTTP needs an application authentication provider"); + } + if(!Boolean.TRUE.equals(qInstance.getEnforcePermissionsInCoreActions())) + { + throw new IllegalArgumentException("MCP over HTTP requires permission enforcement in core actions"); + } + this.qInstance = qInstance; + } + + + + /*************************************************************************** + ** Authenticate, then continue; or answer 401. + ***************************************************************************/ + @Override + public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException + { + HttpServletRequest http = (HttpServletRequest) request; + HttpServletResponse answer = (HttpServletResponse) response; + + String header = http.getHeader("Authorization"); + if(header == null || !header.startsWith(BEARER_PREFIX) || header.length() == BEARER_PREFIX.length()) + { + reject(answer); + return; + } + + QSession session = null; + try + { + QAuthenticationModuleInterface module = new QAuthenticationModuleDispatcher().getQModule(qInstance.getAuthentication()); + Map context = new HashMap<>(); + context.put("accessToken", header.substring(BEARER_PREFIX.length()).trim()); + QContext.init(qInstance, null); + session = module.createSession(qInstance, qInstance.getAuthentication(), context); + } + catch(Exception e) + { + LOG.info("MCP request authentication failed", e); + } + finally + { + QContext.clear(); + } + + if(session == null || session instanceof QSystemUserSession || session.getUser() == null) + { + reject(answer); + return; + } + request.setAttribute(REQUEST_ATTRIBUTE, session); + chain.doFilter(request, response); + } + + + + /*************************************************************************** + ** 401 with a challenge and no detail. + ***************************************************************************/ + private static void reject(HttpServletResponse response) throws IOException + { + response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); + response.setHeader("WWW-Authenticate", "Bearer"); + response.setContentType("application/json"); + response.getWriter().write("{\"error\":\"unauthorized\"}"); + } + + + + /*************************************************************************** + ** The extractor that hands the request's authenticated session to the MCP + ** server, for use when building the transport. + ***************************************************************************/ + public static McpTransportContextExtractor extractor() + { + return request -> + { + Object session = request.getAttribute(REQUEST_ATTRIBUTE); + return session == null ? McpTransportContext.EMPTY : McpTransportContext.create(Map.of(HttpPrincipalMCPSessionProvider.CONTEXT_KEY, session)); + }; + } +} diff --git a/src/test/java/com/kingsrook/qbits/middlewaremcp/McpHttpSecurityTest.java b/src/test/java/com/kingsrook/qbits/middlewaremcp/McpHttpSecurityTest.java new file mode 100644 index 0000000..1d00e2b --- /dev/null +++ b/src/test/java/com/kingsrook/qbits/middlewaremcp/McpHttpSecurityTest.java @@ -0,0 +1,455 @@ +/* + * Copyright 2025 Kingsrook, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.kingsrook.qbits.middlewaremcp; + + +import java.net.http.HttpClient; +import java.net.http.HttpRequest; +import java.net.http.HttpResponse; +import java.sql.Connection; +import java.sql.Statement; +import java.time.Duration; +import java.util.EnumSet; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.UUID; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.kingsrook.qbits.middlewaremcp.model.MCPOperation; +import com.kingsrook.qbits.middlewaremcp.session.HttpPrincipalMCPSessionProvider; +import com.kingsrook.qbits.middlewaremcp.transport.McpBearerAuthenticationFilter; +import com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException; +import com.kingsrook.qqq.backend.core.model.metadata.QAuthenticationType; +import com.kingsrook.qqq.backend.core.model.metadata.QInstance; +import com.kingsrook.qqq.backend.core.model.metadata.authentication.QAuthenticationMetaData; +import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference; +import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData; +import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType; +import com.kingsrook.qqq.backend.core.model.metadata.permissions.PermissionLevel; +import com.kingsrook.qqq.backend.core.model.metadata.permissions.QPermissionRules; +import com.kingsrook.qqq.backend.core.model.metadata.security.QSecurityKeyType; +import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLock; +import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData; +import com.kingsrook.qqq.backend.core.model.session.QSession; +import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession; +import com.kingsrook.qqq.backend.core.model.session.QUser; +import com.kingsrook.qqq.backend.core.modules.authentication.QAuthenticationModuleInterface; +import com.kingsrook.qqq.backend.module.rdbms.jdbc.ConnectionManager; +import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData; +import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSTableBackendDetails; +import io.javalin.Javalin; +import io.modelcontextprotocol.client.McpClient; +import io.modelcontextprotocol.client.McpSyncClient; +import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport; +import io.modelcontextprotocol.server.McpSyncServer; +import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider; +import io.modelcontextprotocol.spec.McpSchema; +import jakarta.servlet.DispatcherType; +import org.eclipse.jetty.ee10.servlet.FilterHolder; +import org.eclipse.jetty.ee10.servlet.ServletHolder; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; + + +/******************************************************************************* + ** The Streamable HTTP transport as a host mounts it, driven by a REAL MCP client + ** (the SDK's own client over HTTP): every request carries its own bearer token, + ** the application's authentication module turns it into that caller's QSession, + ** and the tools run under that session's table permissions and tenant lock. + ** Read-only is the default; writes exist only when enabled, and then still only + ** under the caller's real permissions. + *******************************************************************************/ +class McpHttpSecurityTest +{ + private static final ObjectMapper MAPPER = new ObjectMapper().findAndRegisterModules(); + + private QInstance instance; + private Javalin readOnlyServer; + private Javalin writableServer; + private McpSyncServer readOnlyMcp; + private McpSyncServer writableMcp; + private int readOnlyPort; + private int writablePort; + + + + /******************************************************************************* + ** An application with a tenant-locked table, a table the server does not + ** expose, an exposed table nobody here may read, and two MCP servers. + *******************************************************************************/ + @BeforeEach + void setUp() throws Exception + { + ConnectionManager.resetConnectionProviders(); + RDBMSBackendMetaData backend = new RDBMSBackendMetaData().withName("db").withVendor("h2").withHostName("mem") + .withDatabaseName("mcp_" + UUID.randomUUID().toString().replace("-", "")).withUsername("sa"); + instance = new QInstance(); + instance.setEnforcePermissionsInCoreActions(true); + instance.addBackend(backend); + instance.withInstanceDefaultAuthentication(new QAuthenticationMetaData().withName("tokens").withType(QAuthenticationType.CUSTOM) + .withModuleCodeReference(new QCodeReference(TokenAuthenticationModule.class))); + instance.addSecurityKeyType(new QSecurityKeyType().withName("tenant")); + instance.addTable(table("customer", true)); + instance.addTable(table("vault", false)); + instance.addTable(table("secret", false)); + new com.kingsrook.qqq.backend.core.instances.QInstanceValidator().validate(instance); + + try(Connection connection = ConnectionManager.getConnection(backend); Statement statement = connection.createStatement()) + { + for(String name : List.of("customer", "vault", "secret")) + { + statement.execute("CREATE TABLE " + name + " (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(100), tenant_id INT)"); + } + statement.execute("INSERT INTO customer (name, tenant_id) VALUES ('Acme', 1), ('Bolt', 1), ('Cog', 2)"); + statement.execute("INSERT INTO vault (name, tenant_id) VALUES ('V1', 1)"); + statement.execute("INSERT INTO secret (name, tenant_id) VALUES ('S1', 1)"); + } + + Set exposed = Set.of("customer", "vault"); + readOnlyMcp = mcp(new QMCPMetaData().withServerName("test-readonly").withSessionProvider(new HttpPrincipalMCPSessionProvider()).withExposedTableNames(exposed)); + readOnlyServer = serve(readOnlyMcp); + readOnlyPort = readOnlyServer.port(); + writableMcp = mcp(new QMCPMetaData().withServerName("test-writable").withSessionProvider(new HttpPrincipalMCPSessionProvider()).withExposedTableNames(exposed) + .withDefaultTableOperations(EnumSet.of(MCPOperation.QUERY, MCPOperation.COUNT, MCPOperation.GET, MCPOperation.INSERT))); + writableServer = serve(writableMcp); + writablePort = writableServer.port(); + } + + + + /******************************************************************************* + ** Stop everything. + *******************************************************************************/ + @AfterEach + void tearDown() + { + readOnlyServer.stop(); + writableServer.stop(); + readOnlyMcp.close(); + writableMcp.close(); + } + + + + /******************************************************************************* + ** Without a valid bearer token nothing reaches the MCP server: not initialize, + ** not a cookie, not a basic credential, not a made-up token. + *******************************************************************************/ + @Test + void testUnauthenticatedRequestsAreRefused() throws Exception + { + String initialize = "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"t\",\"version\":\"1\"}}}"; + for(String authorization : new String[] { null, "", "Bearer", "Bearer ", "Basic YWxpY2U6cHc=", "Bearer not-a-token", "bearer alice-token" }) + { + HttpRequest.Builder builder = HttpRequest.newBuilder(java.net.URI.create("http://localhost:" + readOnlyPort + "/mcp")) + .header("Content-Type", "application/json").header("Accept", "application/json, text/event-stream").header("Cookie", "sessionId=alice-token") + .POST(HttpRequest.BodyPublishers.ofString(initialize)); + if(authorization != null) + { + builder.header("Authorization", authorization); + } + HttpResponse response = HttpClient.newHttpClient().send(builder.build(), HttpResponse.BodyHandlers.ofString()); + assertThat(response.statusCode()).as("authorization=" + authorization).isEqualTo(401); + assertThat(response.headers().firstValue("WWW-Authenticate")).contains("Bearer"); + assertThat(response.body()).doesNotContain("serverInfo"); + } + } + + + + /******************************************************************************* + ** initialize, list, read and query as one tenant's user: only what that + ** caller's permissions and tenant allow. + *******************************************************************************/ + @Test + void testAliceSeesOnlyHerPermittedTenantData() throws Exception + { + try(McpSyncClient client = client(readOnlyPort, "alice-token")) + { + McpSchema.InitializeResult init = client.initialize(); + assertThat(init.serverInfo().name()).isEqualTo("test-readonly"); + + List tools = client.listTools().tools().stream().map(McpSchema.Tool::name).toList(); + assertThat(tools).contains("list_tables", "describe_table", "query_customer", "count_customer", "get_customer"); + assertThat(tools).noneMatch(name -> name.startsWith("insert_") || name.startsWith("update_") || name.startsWith("delete_") || name.startsWith("run_process_")); + assertThat(tools).doesNotContain("query_secret"); + assertThat(client.listResources().resources().stream().map(McpSchema.Resource::uri)).contains("qqq://tables"); + assertThat(client.listPrompts().prompts().stream().map(McpSchema.Prompt::name)).contains("explore_table", "summarize_data"); + + // tables: customer only (vault is exposed but alice cannot read it; secret is not exposed) + String tableList = text(client.callTool(new McpSchema.CallToolRequest("list_tables", Map.of()))); + assertThat(tableList).contains("customer").doesNotContain("vault").doesNotContain("secret"); + String resourceList = ((McpSchema.TextResourceContents) client.readResource(new McpSchema.ReadResourceRequest("qqq://tables")).contents().get(0)).text(); + assertThat(resourceList).contains("customer").doesNotContain("vault").doesNotContain("secret"); + String schema = ((McpSchema.TextResourceContents) client.readResource(new McpSchema.ReadResourceRequest("qqq://table/customer/schema")).contents().get(0)).text(); + assertThat(schema).contains("name"); + assertThat(text(client.callTool(new McpSchema.CallToolRequest("describe_table", Map.of("tableName", "customer"))))).contains("tenantId"); + + // not exposed / not visible: reported exactly like a table that does not exist + String missing = text(client.callTool(new McpSchema.CallToolRequest("describe_table", Map.of("tableName", "no_such_table")))); + assertThat(text(client.callTool(new McpSchema.CallToolRequest("describe_table", Map.of("tableName", "secret"))))).isEqualTo(missing.replace("no_such_table", "secret")); + assertThat(text(client.callTool(new McpSchema.CallToolRequest("describe_table", Map.of("tableName", "vault"))))).isEqualTo(missing.replace("no_such_table", "vault")); + String vaultSchema = ((McpSchema.TextResourceContents) client.readResource(new McpSchema.ReadResourceRequest("qqq://table/vault/schema")).contents().get(0)).text(); + assertThat(vaultSchema).contains("not found"); + + // data: tenant 1 only + String query = text(client.callTool(new McpSchema.CallToolRequest("query_customer", Map.of()))); + assertThat(query).contains("Acme").contains("Bolt").doesNotContain("Cog"); + assertThat(text(client.callTool(new McpSchema.CallToolRequest("count_customer", Map.of())))).contains("2"); + + // the other tenant's record, by id, is not available + McpSchema.CallToolResult other = client.callTool(new McpSchema.CallToolRequest("get_customer", Map.of("id", 3))); + assertThat(text(other)).doesNotContain("Cog"); + + // an exposed table she cannot read: refused with the real permission error + McpSchema.CallToolResult denied = client.callTool(new McpSchema.CallToolRequest("query_vault", Map.of())); + assertThat(denied.isError()).isTrue(); + assertThat(text(denied)).containsIgnoringCase("permission").doesNotContain("V1"); + } + } + + + + /******************************************************************************* + ** The same server, another caller: each request is its own caller, so another + ** tenant's user sees only their own rows, and a caller with no permissions is + ** refused everything. + *******************************************************************************/ + @Test + void testOtherActorsAreSeparate() throws Exception + { + try(McpSyncClient bob = client(readOnlyPort, "bob-token"); McpSyncClient eve = client(readOnlyPort, "eve-token"); McpSyncClient alice = client(readOnlyPort, "alice-token")) + { + bob.initialize(); + eve.initialize(); + alice.initialize(); + + String bobRows = text(bob.callTool(new McpSchema.CallToolRequest("query_customer", Map.of()))); + assertThat(bobRows).contains("Cog").doesNotContain("Acme").doesNotContain("Bolt"); + String aliceRows = text(alice.callTool(new McpSchema.CallToolRequest("query_customer", Map.of()))); + assertThat(aliceRows).contains("Acme").doesNotContain("Cog"); + + McpSchema.CallToolResult eveQuery = eve.callTool(new McpSchema.CallToolRequest("query_customer", Map.of())); + assertThat(eveQuery.isError()).isTrue(); + assertThat(text(eveQuery)).doesNotContain("Acme").doesNotContain("Cog"); + assertThat(text(eve.callTool(new McpSchema.CallToolRequest("list_tables", Map.of())))).doesNotContain("customer"); + } + } + + + + /******************************************************************************* + ** Read-only by default: no write tools exist, and a write call is unknown. With + ** writes enabled they still run only under the caller's own permission and + ** tenant lock. + *******************************************************************************/ + @Test + void testMutationsNeedBothOptInAndPermission() throws Exception + { + try(McpSyncClient writer = client(readOnlyPort, "writer-token")) + { + writer.initialize(); + assertThatThrownBy(() -> writer.callTool(new McpSchema.CallToolRequest("insert_customer", Map.of("record", Map.of("name", "X", "tenantId", 1))))).isInstanceOf(RuntimeException.class); + } + + try(McpSyncClient writer = client(writablePort, "writer-token"); McpSyncClient alice = client(writablePort, "alice-token")) + { + writer.initialize(); + alice.initialize(); + assertThat(writer.listTools().tools().stream().map(McpSchema.Tool::name)).contains("insert_customer").doesNotContain("update_customer", "delete_customer"); + + McpSchema.CallToolResult inserted = writer.callTool(new McpSchema.CallToolRequest("insert_customer", Map.of("record", Map.of("name", "Dyna", "tenantId", 1)))); + assertThat(inserted.isError()).as(text(inserted)).isFalse(); + assertThat(text(inserted)).as("insert result").doesNotContain("rror"); + assertThat(text(writer.callTool(new McpSchema.CallToolRequest("query_customer", Map.of())))).contains("Dyna"); + + // the tenant lock applies to the write itself + McpSchema.CallToolResult crossTenant = writer.callTool(new McpSchema.CallToolRequest("insert_customer", Map.of("record", Map.of("name", "Sneaky", "tenantId", 2)))); + assertThat(text(crossTenant)).doesNotContain("\"id\" : 5"); + try(McpSyncClient bob = client(writablePort, "bob-token")) + { + bob.initialize(); + assertThat(text(bob.callTool(new McpSchema.CallToolRequest("query_customer", Map.of())))).doesNotContain("Sneaky").doesNotContain("Dyna"); + } + + // alice has no insert permission: refused, nothing written + McpSchema.CallToolResult aliceInsert = alice.callTool(new McpSchema.CallToolRequest("insert_customer", Map.of("record", Map.of("name", "Nope", "tenantId", 1)))); + assertThat(aliceInsert.isError()).isTrue(); + assertThat(text(alice.callTool(new McpSchema.CallToolRequest("query_customer", Map.of())))).doesNotContain("Nope").doesNotContain("Sneaky"); + } + } + + + + /******************************************************************************* + ** The server can never run as a fixed or system identity over HTTP, and the HTTP + ** transport will not start without authentication and enforcement. + *******************************************************************************/ + @Test + void testNoFixedOrSystemIdentity() throws Exception + { + HttpPrincipalMCPSessionProvider provider = new HttpPrincipalMCPSessionProvider(); + assertThatThrownBy(() -> provider.createSession(null)).isInstanceOf(QAuthenticationException.class); + + QInstance noEnforcement = new QInstance(); + noEnforcement.withInstanceDefaultAuthentication(new QAuthenticationMetaData().withName("tokens").withType(QAuthenticationType.CUSTOM) + .withModuleCodeReference(new QCodeReference(TokenAuthenticationModule.class))); + assertThatThrownBy(() -> new McpBearerAuthenticationFilter(noEnforcement)).isInstanceOf(IllegalArgumentException.class).hasMessageContaining("enforcement"); + assertThatThrownBy(() -> new McpBearerAuthenticationFilter(new QInstance())).isInstanceOf(IllegalArgumentException.class); + + // a system session is never accepted as a principal, even from a token + try(McpSyncClient system = client(readOnlyPort, "system-token")) + { + assertThatThrownBy(system::initialize).isInstanceOf(RuntimeException.class); + } + } + + + + /******************************************************************************* + ** The text of a tool result. + *******************************************************************************/ + private static String text(McpSchema.CallToolResult result) + { + return ((McpSchema.TextContent) result.content().get(0)).text(); + } + + + + /******************************************************************************* + ** A real MCP client over HTTP with its own bearer token. + *******************************************************************************/ + private static McpSyncClient client(int port, String token) + { + HttpClientStreamableHttpTransport transport = HttpClientStreamableHttpTransport.builder("http://localhost:" + port).endpoint("/mcp") + .customizeRequest(request -> request.header("Authorization", "Bearer " + token)).build(); + return McpClient.sync(transport).requestTimeout(Duration.ofSeconds(20)).initializationTimeout(Duration.ofSeconds(20)).build(); + } + + + + /******************************************************************************* + ** A table; the first is tenant-locked. + *******************************************************************************/ + private static QTableMetaData table(String name, boolean tenantLocked) + { + QTableMetaData table = new QTableMetaData().withName(name).withBackendName("db").withPrimaryKeyField("id") + .withBackendDetails(new RDBMSTableBackendDetails().withTableName(name)) + .withPermissionRules(new QPermissionRules().withLevel(PermissionLevel.READ_WRITE_PERMISSIONS).withPermissionBaseName(name)) + .withField(new QFieldMetaData("id", QFieldType.INTEGER).withBackendName("id").withIsEditable(false)) + .withField(new QFieldMetaData("name", QFieldType.STRING).withBackendName("name").withMaxLength(100)) + .withField(new QFieldMetaData("tenantId", QFieldType.INTEGER).withBackendName("tenant_id")); + table.withRecordSecurityLock(new RecordSecurityLock().withSecurityKeyType("tenant").withFieldName("tenantId")); + return table; + } + + + + /******************************************************************************* + ** An MCP server with the metadata, on the streamable servlet transport that + ** extracts the authenticated session of each request. + *******************************************************************************/ + private final java.util.Map transports = new java.util.HashMap<>(); + + + + /******************************************************************************* + ** Build one. + *******************************************************************************/ + private McpSyncServer mcp(QMCPMetaData metaData) + { + HttpServletStreamableServerTransportProvider transport = HttpServletStreamableServerTransportProvider.builder() + .objectMapper(MAPPER).mcpEndpoint("/mcp").contextExtractor(McpBearerAuthenticationFilter.extractor()).build(); + McpSyncServer server = QMCPServer.build(instance, metaData, transport); + transports.put(server, transport); + return server; + } + + + + /******************************************************************************* + ** Mount the transport, behind the authentication filter, in a Javalin server. + *******************************************************************************/ + private Javalin serve(McpSyncServer server) + { + HttpServletStreamableServerTransportProvider transport = transports.get(server); + return Javalin.create(config -> config.jetty.modifyServletContextHandler(context -> + { + context.addFilter(new FilterHolder(new McpBearerAuthenticationFilter(instance)), "/mcp/*", EnumSet.of(DispatcherType.REQUEST, DispatcherType.ASYNC)); + context.addServlet(new ServletHolder("mcp", transport), "/mcp/*"); + })).start(0); + } + + + + /******************************************************************************* + ** Tokens to synthetic identities: the application's authentication module. + *******************************************************************************/ + public static class TokenAuthenticationModule implements QAuthenticationModuleInterface + { + /*************************************************************************** + ** Resolve the token (a real module would verify it with its provider). + ***************************************************************************/ + @Override + public QSession createSession(QInstance qInstance, Map context) throws QAuthenticationException + { + String token = context.get("accessToken"); + if(token == null) + { + throw new QAuthenticationException("no token"); + } + QSession session = switch(token) + { + case "alice-token" -> identity("alice", 1, "customer.read"); + case "bob-token" -> identity("bob", 2, "customer.read"); + case "eve-token" -> identity("eve", 1); + case "writer-token" -> identity("writer", 1, "customer.read", "customer.write"); + case "system-token" -> new QSystemUserSession(); + default -> throw new QAuthenticationException("unknown token"); + }; + return session; + } + + + + /*************************************************************************** + ** A synthetic user. + ***************************************************************************/ + private static QSession identity(String user, int tenant, String... permissions) + { + QSession session = new QSession().withUser(new QUser().withIdReference(user).withFullName(user)).withSecurityKeyValue("tenant", tenant); + session.setUuid(UUID.randomUUID().toString()); + session.setIdReference(session.getUuid()); + session.setPermissions(Set.of(permissions)); + return session; + } + + + + /*************************************************************************** + ** Always valid for this test module. + ***************************************************************************/ + @Override + public boolean isSessionValid(QInstance instance, QSession session) + { + return true; + } + } +} diff --git a/src/test/java/com/kingsrook/qbits/middlewaremcp/TestUtils.java b/src/test/java/com/kingsrook/qbits/middlewaremcp/TestUtils.java index 7c4fafe..d9e6962 100644 --- a/src/test/java/com/kingsrook/qbits/middlewaremcp/TestUtils.java +++ b/src/test/java/com/kingsrook/qbits/middlewaremcp/TestUtils.java @@ -51,7 +51,7 @@ public class TestUtils public static QInstance defineInstance() { QInstance qInstance = new QInstance(); - qInstance.setAuthentication(new QAuthenticationMetaData() + qInstance.withInstanceDefaultAuthentication(new QAuthenticationMetaData() .withName("mock") .withType(QAuthenticationType.FULLY_ANONYMOUS)); diff --git a/src/test/java/com/kingsrook/qbits/middlewaremcp/tools/RunProcessToolHandlerTest.java b/src/test/java/com/kingsrook/qbits/middlewaremcp/tools/RunProcessToolHandlerTest.java index 07d6ef3..2db7824 100644 --- a/src/test/java/com/kingsrook/qbits/middlewaremcp/tools/RunProcessToolHandlerTest.java +++ b/src/test/java/com/kingsrook/qbits/middlewaremcp/tools/RunProcessToolHandlerTest.java @@ -65,7 +65,7 @@ class RunProcessToolHandlerTest qInstance.addProcess(new QProcessMetaData() .withName(PROCESS_NAME) .withLabel("Test Process") - .addStep(new QBackendStepMetaData() + .withStep(new QBackendStepMetaData() .withName("step1") .withCode(new QCodeReference(EchoBackendStep.class.getName(), QCodeType.JAVA)))); -- 2.54.0