@samanhappy/mcphub 1.0.32 → 1.0.34

package/dist/clients/openapi.js

@@ -1,4 +1,5 @@
 import axios from 'axios';
+import { randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { CookieJar } from 'tough-cookie';
 import SwaggerParser from '@apidevtools/swagger-parser';
@@ -6,6 +7,51 @@ import * as yaml from 'js-yaml';
 import { assertSafeUrl, UnsafeUrlError, createRedirectValidatingFetch } from '../utils/ssrf.js';
 import { getUserDao } from '../dao/index.js';
 import { sanitizeStringForLogging, createSafeJSON } from '../utils/serialization.js';
+import { buildMultipartParts, encodeFormUrlEncoded, makeMultipartBodySchemaModelFriendly, selectRequestBodyContent, serializeMultipartBody, } from '../utils/openApiRequestBody.js';
+// Encodes a substituted path parameter following OpenAPI's default
+// `style: simple, explode: false`: primitives whole, arrays and objects part
+// by part, joined with literal commas (#1083).
+function encodePathParameterValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => encodeURIComponent(String(item))).join(',');
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.entries(value)
+            .map(([key, val]) => `${encodeURIComponent(key)},${encodeURIComponent(String(val))}`)
+            .join(',');
+    }
+    return encodeURIComponent(String(value));
+}
+function isPrintableAscii(value) {
+    return /^[\x20-\x7E]*$/.test(value);
+}
+// Strict base64 check: the alphabet plus canonical padding must round-trip
+// through decode → encode unchanged. Buffer.from alone is too lenient (it
+// silently drops invalid characters), which would misread raw secrets as
+// encoded ones.
+function tryDecodeBase64Utf8(value) {
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+        return null;
+    }
+    const decoded = Buffer.from(value, 'base64').toString('utf8');
+    const stripPadding = (input) => input.replace(/=+$/, '');
+    return stripPadding(Buffer.from(decoded, 'utf8').toString('base64')) === stripPadding(value)
+        ? decoded
+        : null;
+}
+// HTTP Basic transmits base64("user:password"), but users reasonably enter the
+// raw `user:pass` pair into the credentials field (#1079). Encode such values
+// automatically; keep a value only when it decodes to printable
+// `user:pass`-shaped text (contains ':'), the conservative test for a
+// credential that was pre-encoded upstream. Anything ambiguous (e.g. a token
+// without a colon) is treated as raw and encoded.
+function toBasicAuthCredentials(credentials) {
+    const decoded = tryDecodeBase64Utf8(credentials);
+    if (decoded !== null && isPrintableAscii(decoded) && decoded.includes(':')) {
+        return credentials;
+    }
+    return Buffer.from(credentials, 'utf8').toString('base64');
+}
 export class OpenAPIClient {
     constructor(config, options = {}) {
         this.config = config;
@@ -21,20 +67,47 @@ export class OpenAPIClient {
         if (!config.openapi?.url && !config.openapi?.schema) {
             throw new Error('OpenAPI URL or schema is required');
         }
-        // Initial baseUrl, will be updated from OpenAPI servers field in initialize()
+        // Initial baseUrl, will be updated from OpenAPI servers field in initialize().
+        // It is only used to resolve relative request paths (see callTool), never
+        // installed as the axios instance's default baseURL. Each request's
+        // effective URL is SSRF-validated explicitly before dispatch, so a
+        // user-derived default baseURL must not taint this.httpClient — CodeQL
+        // tracks a client's default baseURL as the host of every request it makes.
         this.baseUrl = config.openapi?.url ? this.extractBaseUrl(config.openapi.url) : '';
         this.securityConfig = config.openapi.security;
         this.persistOAuth2Token = options.persistOAuth2Token;
-        this.httpClient = axios.create({
-            baseURL: this.baseUrl,
+        this.httpClient = this.createHttpClient(config);
+        const mainCookie = this.applySecurityToClient(this.httpClient, this.securityConfig);
+        this.staticCookieHeader = mainCookie.staticCookieHeader;
+        const specSecurity = config.openapi?.specSecurity;
+        if (specSecurity && specSecurity.type !== 'none') {
+            // The dynamic OAuth2 client-credentials flow persists refreshed tokens
+            // back into `security`, so `specSecurity` only supports a static token.
+            if ((specSecurity.type === 'oauth2' && !specSecurity.oauth2?.token) ||
+                (specSecurity.type === 'openIdConnect' && !specSecurity.openIdConnect?.token)) {
+                throw new Error('openapi.specSecurity: oauth2/openIdConnect requires a pre-obtained token; dynamic token fetch is only supported for openapi.security');
+            }
+            this.specHttpClient = this.createHttpClient(config);
+            const specCookie = this.applySecurityToClient(this.specHttpClient, specSecurity);
+            this.specStaticCookieHeader = specCookie.staticCookieHeader;
+        }
+    }
+    // Shared instance factory so the main client and the spec-download client
+    // (#1079) get identical base behavior: no redirects (credentials must never
+    // cross origins), OpenAPI array query serialization, and operator-supplied
+    // static headers.
+    createHttpClient(config) {
+        return axios.create({
             timeout: config.options?.timeout || 30000,
             maxRedirects: 0,
+            // Serialize array query params per OpenAPI's default `style: form, explode: true`
+            // (`id=a&id=b`) instead of axios's bracket form `id[]=a&id[]=b` (#1080).
+            paramsSerializer: { indexes: null },
             headers: {
                 'Content-Type': 'application/json',
                 ...config.headers,
             },
         });
-        this.setupSecurity();
     }
     extractBaseUrl(specUrl) {
         try {
@@ -46,57 +119,68 @@ export class OpenAPIClient {
             return '';
         }
     }
-    setupSecurity() {
-        if (!this.securityConfig || this.securityConfig.type === 'none') {
-            return;
+    // Apply one OpenAPISecurityConfig onto a specific axios instance: default
+    // headers for header-based credentials, a request interceptor for query
+    // params, and a returned static cookie for the caller to manage (cookies
+    // cannot live in axios defaults). Both `security` and `specSecurity` (#1079)
+    // go through here so the two credential slots behave identically.
+    applySecurityToClient(client, securityConfig) {
+        if (!securityConfig || securityConfig.type === 'none') {
+            return {};
         }
-        switch (this.securityConfig.type) {
-            case 'apiKey':
-                if (this.securityConfig.apiKey) {
-                    const { name, in: location, value } = this.securityConfig.apiKey;
-                    if (location === 'header') {
-                        this.httpClient.defaults.headers.common[name] = value;
+        switch (securityConfig.type) {
+            case 'apiKey': {
+                if (securityConfig.apiKey) {
+                    const { name, in: location, value } = securityConfig.apiKey;
+                    // An empty/absent value means the credential has not been supplied
+                    // yet ("needs credentials"); skip injection rather than sending a
+                    // broken empty header/param/cookie (#1077).
+                    if (location === 'header' && value) {
+                        client.defaults.headers.common[name] = value;
                     }
-                    else if (location === 'query') {
-                        this.httpClient.interceptors.request.use((config) => {
+                    else if (location === 'query' && value) {
+                        client.interceptors.request.use((config) => {
                             config.params = { ...config.params, [name]: value };
                             return config;
                         });
                     }
-                    else if (location === 'cookie') {
-                        this.staticCookieHeader = `${name}=${value}`;
+                    else if (location === 'cookie' && value) {
+                        return { staticCookieHeader: `${name}=${value}` };
                     }
                 }
-                break;
-            case 'http':
-                if (this.securityConfig.http) {
-                    const { scheme, credentials } = this.securityConfig.http;
+                return {};
+            }
+            case 'http': {
+                if (securityConfig.http) {
+                    const { scheme, credentials } = securityConfig.http;
                     if (scheme === 'bearer' && credentials) {
-                        this.httpClient.defaults.headers.common['Authorization'] = `Bearer ${credentials}`;
+                        client.defaults.headers.common['Authorization'] = `Bearer ${credentials}`;
                     }
                     else if (scheme === 'basic' && credentials) {
-                        this.httpClient.defaults.headers.common['Authorization'] = `Basic ${credentials}`;
+                        // Accept the raw `user:pass` form and pre-encoded base64 alike (#1079).
+                        const trimmed = credentials.trim();
+                        if (trimmed) {
+                            client.defaults.headers.common['Authorization'] =
+                                `Basic ${toBasicAuthCredentials(trimmed)}`;
+                        }
                     }
                 }
-                break;
+                return {};
+            }
             case 'oauth2':
-                if (this.securityConfig.oauth2?.token) {
-                    this.setAuthorizationHeader(this.securityConfig.oauth2.token);
-                }
-                break;
+                this.setAuthorizationHeader(client, securityConfig.oauth2?.token);
+                return {};
             case 'openIdConnect':
-                if (this.securityConfig.openIdConnect?.token) {
-                    this.setAuthorizationHeader(this.securityConfig.openIdConnect.token);
-                }
-                break;
+                this.setAuthorizationHeader(client, securityConfig.openIdConnect?.token);
+                return {};
         }
     }
-    setAuthorizationHeader(token) {
+    setAuthorizationHeader(client, token) {
         if (token) {
-            this.httpClient.defaults.headers.common['Authorization'] = 'Bearer ' + token;
+            client.defaults.headers.common['Authorization'] = 'Bearer ' + token;
             return;
         }
-        delete this.httpClient.defaults.headers.common['Authorization'];
+        delete client.defaults.headers.common['Authorization'];
     }
     getOAuth2Config() {
         return this.securityConfig?.type === 'oauth2' ? this.securityConfig.oauth2 : undefined;
@@ -115,7 +199,7 @@ export class OpenAPIClient {
         if (this.config.openapi?.security?.oauth2) {
             this.config.openapi.security.oauth2 = oauth2;
         }
-        this.setAuthorizationHeader(undefined);
+        this.setAuthorizationHeader(this.httpClient, undefined);
         await this.persistOAuth2Token?.({ ...oauth2 });
         return true;
     }
@@ -143,7 +227,7 @@ export class OpenAPIClient {
         if (this.config.openapi?.security?.oauth2) {
             this.config.openapi.security.oauth2 = oauth2;
         }
-        this.setAuthorizationHeader(token);
+        this.setAuthorizationHeader(this.httpClient, token);
         await this.persistOAuth2Token?.(oauth2);
     }
     async fetchOAuth2ClientCredentialsToken(oauth2) {
@@ -160,9 +244,15 @@ export class OpenAPIClient {
         if (Array.isArray(oauth2.scopes) && oauth2.scopes.length > 0) {
             body.set('scope', oauth2.scopes.join(' '));
         }
+        // Validate OAuth token endpoints with the same owner-scoped SSRF policy as
+        // specification and tool requests. This is especially important for the
+        // unsaved preview endpoint, which accepts the complete OpenAPI config.
+        const safeTokenUrl = await assertSafeUrl(oauth2.tokenUrl, {
+            allowInternal: this.allowInternalNetworks,
+        });
         const response = await this.httpClient.request({
             method: 'post',
-            url: oauth2.tokenUrl,
+            url: safeTokenUrl,
             baseURL: undefined,
             headers: {
                 'Content-Type': 'application/x-www-form-urlencoded',
@@ -185,12 +275,12 @@ export class OpenAPIClient {
             return undefined;
         }
         if (this.hasValidOAuth2Token(oauth2)) {
-            this.setAuthorizationHeader(oauth2.token);
+            this.setAuthorizationHeader(this.httpClient, oauth2.token);
             return oauth2.token;
         }
         if (!oauth2.tokenUrl || !oauth2.clientId) {
             if (oauth2.token) {
-                this.setAuthorizationHeader(oauth2.token);
+                this.setAuthorizationHeader(this.httpClient, oauth2.token);
             }
             return oauth2.token;
         }
@@ -220,27 +310,37 @@ export class OpenAPIClient {
             this.refGuardRejection = undefined;
             // Parse and dereference the OpenAPI specification
             if (this.config.openapi?.url) {
-                // Fetch the document through the authenticated httpClient (carries
-                // config.headers + security credentials from setupSecurity, and uses
-                // maxRedirects: 0 so credentials are never forwarded across a
-                // cross-origin redirect). SwaggerParser's own resolver is bypassed for
-                // the main document so its (unauthenticated) headers never see the
-                // credentials; external $ref resolution still uses that resolver and
-                // therefore receives no auth by default.
+                // SwaggerParser's own resolver is bypassed for the main document so
+                // its (unauthenticated) headers never see the credentials; external
+                // $ref resolution still uses that resolver and therefore receives no
+                // auth by default.
                 const specUrl = this.config.openapi.url;
-                await assertSafeUrl(specUrl, { allowInternal: this.allowInternalNetworks });
+                const safeSpecUrl = await assertSafeUrl(specUrl, {
+                    allowInternal: this.allowInternalNetworks,
+                });
                 const requestConfig = {
                     responseType: 'text',
                     transformResponse: [(data) => data],
                 };
+                // Download through the client whose credentials match the spec
+                // endpoint: the dedicated specHttpClient when `specSecurity` names one
+                // (#1079), otherwise the main client whose defaults already carry
+                // `security` (and the apiKey-in-query interceptor). Uses maxRedirects:
+                // 0 so credentials are never forwarded across a cross-origin redirect;
+                // external $ref resolution keeps using the unauthenticated resolver
+                // from guardedRefResolveOptions below.
+                const specClient = this.specHttpClient ?? this.httpClient;
+                const specCookie = this.specHttpClient
+                    ? this.specStaticCookieHeader
+                    : this.staticCookieHeader;
                 // The static apiKey.in:'cookie' value is otherwise only injected in
-                // callTool; apply it here too so cookie-protected spec URLs load.
-                if (this.staticCookieHeader) {
-                    requestConfig.headers = { Cookie: this.staticCookieHeader };
+                // callTool; apply it here so cookie-protected spec URLs load.
+                if (specCookie) {
+                    requestConfig.headers = { Cookie: specCookie };
                 }
-                const response = await this.httpClient.get(specUrl, requestConfig);
+                const response = await specClient.get(safeSpecUrl, requestConfig);
                 const raw = typeof response.data === 'string' ? response.data : String(response.data);
-                this.spec = (await SwaggerParser.dereference(specUrl, this.parseSpecDocument(raw), this.guardedRefResolveOptions()));
+                this.spec = (await SwaggerParser.dereference(safeSpecUrl, this.parseSpecDocument(raw), this.guardedRefResolveOptions()));
             }
             else if (this.config.openapi?.schema) {
                 // For schema object, we need to pass it as a cloned object
@@ -298,18 +398,22 @@ export class OpenAPIClient {
                     order: 1,
                     canRead: (file) => /^https?:\/\//i.test(file.url),
                     read: async (file) => {
+                        let safeRefUrl;
                         try {
-                            await assertSafeUrl(file.url, { allowInternal: this.allowInternalNetworks });
+                            safeRefUrl = await assertSafeUrl(file.url, {
+                                allowInternal: this.allowInternalNetworks,
+                            });
                         }
                         catch (error) {
                             rejectUnsafe(error);
+                            return '';
                         }
                         // Plain fetch, NOT this.httpClient: default auth headers and
                         // interceptors must never be forwarded cross-origin to $ref
                         // targets (#1044). Redirects are followed manually with every hop
                         // re-validated by the guard.
                         const safeFetch = createRedirectValidatingFetch((url, init) => fetch(url, init), this.allowInternalNetworks);
-                        const response = await safeFetch(file.url, { method: 'GET', headers: {} });
+                        const response = await safeFetch(safeRefUrl, { method: 'GET', headers: {} });
                         const buf = await response.arrayBuffer();
                         return new TextDecoder().decode(buf);
                     },
@@ -378,8 +482,6 @@ export class OpenAPIClient {
                 this.baseUrl = `${originalUrl.protocol}//${originalUrl.host}/${serverUrl}`;
             }
         }
-        // Update HTTP client's baseURL
-        this.httpClient.defaults.baseURL = this.baseUrl;
     }
     extractTools() {
         if (!this.spec?.paths) {
@@ -421,15 +523,30 @@ export class OpenAPIClient {
                     operationName = uniqueName;
                 }
                 generatedNames.add(operationName);
+                // Resolve the operation's declared request-body content type once so
+                // schema advertisement below and outgoing serialization in callTool
+                // stay symmetric (#1078).
+                const declaredRequestBody = operation.requestBody && 'content' in operation.requestBody
+                    ? operation.requestBody
+                    : undefined;
+                const requestBodySelection = selectRequestBodyContent(declaredRequestBody);
+                let description = operation.summary || operation.description || `${method.toUpperCase()} ${path}`;
+                // A body whose content type the hub cannot serialize used to produce a
+                // silent zero-argument tool that models would retry forever. Mark such
+                // operations visibly in the description instead (#1078).
+                if (declaredRequestBody && !requestBodySelection) {
+                    const declaredTypes = Object.keys(declaredRequestBody.content ?? {}).join(', ');
+                    description += ` [Unsupported request body content type(s): ${declaredTypes} — only application/json, application/x-www-form-urlencoded and multipart/form-data can be sent by MCPHub.]`;
+                }
                 const tool = {
                     name: operationName,
-                    description: operation.summary || operation.description || `${method.toUpperCase()} ${path}`,
+                    description,
                     // SwaggerParser.dereference turns recursive $ref schemas into live
                     // circular references on the dereferenced spec objects. generateInputSchema
                     // references those objects directly, so without sanitization every
                     // downstream serializer (tokenCost, getServerConfig, MCP ListTools,
                     // embeddings) throws "Converting circular structure to JSON". See #959.
-                    inputSchema: createSafeJSON(this.generateInputSchema(operation, path, method)),
+                    inputSchema: createSafeJSON(this.generateInputSchema(operation, path, method, requestBodySelection)),
                     operationId: operation.operationId || operationName,
                     method: method,
                     path,
@@ -441,7 +558,7 @@ export class OpenAPIClient {
             }
         }
     }
-    generateInputSchema(operation, _path, _method) {
+    generateInputSchema(operation, _path, _method, requestBodySelection) {
         const schema = {
             type: 'object',
             properties: {},
@@ -482,12 +599,18 @@ export class OpenAPIClient {
                 }
             }
         }
-        // Handle request body
-        if (operation.requestBody && 'content' in operation.requestBody) {
+        // Handle request body. The advertised schema must match what callTool can
+        // serialize, so key off the same resolved content type selection (#1078):
+        // JSON and urlencoded bodies are exposed as-is; multipart bodies are
+        // rewritten so binary fields accept base64-encoded strings.
+        if (operation.requestBody && 'content' in operation.requestBody && requestBodySelection) {
             const requestBody = operation.requestBody;
-            const jsonContent = requestBody.content?.['application/json'];
-            if (jsonContent?.schema) {
-                properties['body'] = jsonContent.schema;
+            const selectedSchema = requestBodySelection.mediaType.schema;
+            if (selectedSchema) {
+                properties['body'] =
+                    requestBodySelection.contentType === 'multipart/form-data'
+                        ? makeMultipartBodySchemaModelFriendly(selectedSchema)
+                        : selectedSchema;
                 if (requestBody.required) {
                     required.push('body');
                 }
@@ -523,9 +646,14 @@ export class OpenAPIClient {
             const pathParams = tool.parameters?.filter((p) => p.in === 'path') || [];
             for (const param of pathParams) {
                 const value = args[param.name];
-                if (value !== undefined) {
-                    url = url.replace(`{${param.name}}`, String(value));
+                if (value === undefined || value === null) {
+                    // Path parameters are required by the OpenAPI spec; fail fast rather
+                    // than sending a request whose `{placeholder}` can only 404 (#1083).
+                    throw new Error(`Required path parameter '${param.name}' is missing`);
                 }
+                // Values come from model output, so encode them to keep URL-significant
+                // characters ('/', '?', '#', '%') from changing the endpoint (#1083).
+                url = url.replace(`{${param.name}}`, encodePathParameterValue(value));
             }
             // Build query parameters
             const queryParams = {};
@@ -542,9 +670,41 @@ export class OpenAPIClient {
                 url,
                 params: queryParams,
             };
-            // Add request body if applicable
-            if (args.body && ['post', 'put', 'patch'].includes(tool.method)) {
-                requestConfig.data = args.body;
+            // Add request body if applicable. Key off the operation's own spec rather
+            // than a method allowlist: some APIs declare required bodies on DELETE
+            // (bulk deletes), and RFC 9110 §9.3.5 permits content when the origin
+            // server has indicated support for it — which a requestBody declaration
+            // in its OpenAPI document is. Keeps schema advertisement and sending
+            // symmetric (#1084). The body is serialized according to the content type
+            // resolved from the same spec the tool schema was built from (#1078).
+            let requestBodyContentType;
+            if (args.body !== undefined && tool.requestBody) {
+                const selection = selectRequestBodyContent(tool.requestBody);
+                if (!selection) {
+                    const declaredTypes = Object.keys(tool.requestBody.content ?? {}).join(', ');
+                    throw new Error(`Tool '${toolName}' declares a request body with unsupported content type(s): ${declaredTypes}. Only application/json, application/x-www-form-urlencoded and multipart/form-data can be sent by MCPHub.`);
+                }
+                switch (selection.contentType) {
+                    case 'application/json':
+                        requestConfig.data = args.body;
+                        break;
+                    case 'application/x-www-form-urlencoded':
+                        requestConfig.data = encodeFormUrlEncoded(args.body);
+                        requestBodyContentType = 'application/x-www-form-urlencoded';
+                        break;
+                    case 'multipart/form-data': {
+                        const boundary = `----MCPHubBoundary${randomUUID().replace(/-/g, '')}`;
+                        // The spec is dereferenced before tools are built, so the schema
+                        // cannot still be a $ref here.
+                        const bodySchema = selection.mediaType.schema;
+                        const parts = buildMultipartParts(args.body, bodySchema);
+                        requestConfig.data = serializeMultipartBody(parts, boundary);
+                        // The boundary must travel with the header, so it is set explicitly
+                        // per request rather than left to axios.
+                        requestBodyContentType = `multipart/form-data; boundary=${boundary}`;
+                        break;
+                    }
+                }
             }
             // Collect all headers to be sent
             const allHeaders = {};
@@ -564,6 +724,11 @@ export class OpenAPIClient {
                     }
                 }
             }
+            // Form and multipart bodies override the client-wide JSON Content-Type
+            // default for this request only (#1078).
+            if (requestBodyContentType) {
+                allHeaders['Content-Type'] = requestBodyContentType;
+            }
             // Set headers if any were collected
             if (Object.keys(allHeaders).length > 0) {
                 requestConfig.headers = allHeaders;
@@ -574,15 +739,34 @@ export class OpenAPIClient {
             // final URL rather than trusting either alone.
             resolvedTarget = null;
             try {
-                resolvedTarget = new URL(String(requestConfig.url ?? '/'), this.baseUrl || undefined);
+                // Join the operation path onto the server-declared base path with
+                // append semantics, matching axios's combineURLs before #937 and the
+                // OpenAPI servers+paths model: `new URL` reference resolution would
+                // drop the base path for root-absolute paths ('/ping' against
+                // 'http://host/api' resolves to '/ping'), 404-ing every tool call
+                // (#1098). Absolute URLs bypass the join and resolve as-is.
+                let joinedPath = String(requestConfig.url ?? '/');
+                let resolveBase = this.baseUrl || undefined;
+                if (resolveBase && !/^https?:\/\//i.test(joinedPath)) {
+                    const parsedBase = new URL(resolveBase);
+                    const basePath = parsedBase.pathname.replace(/\/+$/, '');
+                    if (basePath) {
+                        joinedPath = `${basePath}/${joinedPath.replace(/^\/+/, '')}`;
+                    }
+                    resolveBase = parsedBase.origin;
+                }
+                resolvedTarget = new URL(joinedPath, resolveBase);
             }
             catch {
                 // relative path with no base — no host to validate; axios surfaces the error
             }
             if (resolvedTarget) {
-                await assertSafeUrl(resolvedTarget.href, {
+                const safeTargetUrl = await assertSafeUrl(resolvedTarget.href, {
                     allowInternal: this.allowInternalNetworks,
                 });
+                const safeTarget = new URL(safeTargetUrl);
+                requestConfig.baseURL = safeTarget.origin;
+                requestConfig.url = `${safeTarget.pathname}${safeTarget.search}`;
             }
             const cookieSessionEnabled = this.isCookieSessionEnabled(sessionId);
             // Inject cookies when either the dynamic session store is active for this
@@ -650,6 +834,189 @@ export class OpenAPIClient {
     getSpec() {
         return this.spec;
     }
+    // ── Declared-security resolution (#1077) ─────────────────────────────────
+    //
+    // The import path reads the effective `security` requirement the spec
+    // declares and maps it onto MCPHub's OpenAPISecurityConfig so the form can
+    // prefill type/scheme/name fields. Only structural fields are ever produced
+    // — a spec cannot contain the secret, so value / credentials / token stay
+    // empty for the user.
+    /**
+     * Resolve the effective security requirement the (already parsed) spec
+     * declares and map it onto MCPHub's security model for form prefill.
+     *
+     * OpenAPI 3.x rules applied here:
+     *  - an operation-level `security` overrides the root-level one for that
+     *    operation; operations without one inherit the root requirement;
+     *  - `security: []` explicitly disables auth for that scope;
+     *  - each requirement is an OR-list of named schemes (from
+     *    `components.securitySchemes`); a single scheme may be repeated in an
+     *    AND-list with its required scopes.
+     *
+     * The first requirement whose scheme maps onto MCPHub's model (apiKey,
+     * http/basic|bearer, oauth2, openIdConnect) is returned as `prefill`.
+     */
+    getDeclaredSecurity() {
+        const none = {
+            declared: false,
+            supported: false,
+            summary: '',
+            alternatives: 0,
+            requiresCredentials: false,
+        };
+        if (!this.spec) {
+            return none;
+        }
+        const rootSecurity = Array.isArray(this.spec.security) ? this.spec.security : undefined;
+        // An explicit operation-level requirement is the most specific declaration
+        // in the document (it overrides the root default for that operation), so it
+        // wins for prefill; the root requirement is the fallback default.
+        const effective = this.firstOperationSecurity() ??
+            (rootSecurity && rootSecurity.length > 0 ? rootSecurity : undefined);
+        if (!effective || effective.length === 0) {
+            return none;
+        }
+        const schemes = this.spec.components?.securitySchemes ?? {};
+        return this.mapSecurityRequirement(effective, schemes);
+    }
+    // Per OpenAPI 3.x, an operation without a `security` field inherits the
+    // root-level requirement. Return the first operation that declares one — the
+    // most specific security statement in the document — so the prefill reflects
+    // what operations actually require rather than only the root default.
+    firstOperationSecurity() {
+        if (!this.spec?.paths) {
+            return undefined;
+        }
+        const methods = ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'trace'];
+        for (const pathItem of Object.values(this.spec.paths)) {
+            if (!pathItem) {
+                continue;
+            }
+            for (const method of methods) {
+                const operation = pathItem[method];
+                if (operation?.security && operation.security.length > 0) {
+                    return operation.security;
+                }
+            }
+        }
+        return undefined;
+    }
+    mapSecurityRequirement(requirement, schemes) {
+        let firstUnsupported;
+        for (const alternative of requirement) {
+            for (const schemeName of Object.keys(alternative)) {
+                const scheme = schemes[schemeName];
+                if (!scheme || '$ref' in scheme) {
+                    // Unknown name or an unresolved reference — try the next alternative.
+                    continue;
+                }
+                const mapped = this.mapSecurityScheme(schemeName, scheme);
+                if (mapped.ok) {
+                    return {
+                        declared: true,
+                        supported: true,
+                        prefill: mapped.prefill,
+                        summary: mapped.summary,
+                        alternatives: requirement.length,
+                        requiresCredentials: true,
+                        ...(mapped.cookieHint ? { cookieHint: true } : {}),
+                    };
+                }
+                firstUnsupported ?? (firstUnsupported = {
+                    declared: true,
+                    supported: false,
+                    summary: mapped.summary,
+                    alternatives: requirement.length,
+                    requiresCredentials: false,
+                    unsupportedReason: mapped.unsupportedReason,
+                });
+            }
+        }
+        return (firstUnsupported ?? {
+            declared: true,
+            supported: false,
+            summary: 'unknown security scheme',
+            alternatives: requirement.length,
+            requiresCredentials: false,
+            unsupportedReason: 'The spec declares a security scheme MCPHub cannot recognize.',
+        });
+    }
+    mapSecurityScheme(schemeName, scheme) {
+        switch (scheme.type) {
+            case 'http':
+                if (scheme.scheme === 'bearer') {
+                    return {
+                        ok: true,
+                        prefill: {
+                            type: 'http',
+                            http: {
+                                scheme: 'bearer',
+                                ...(scheme.bearerFormat ? { bearerFormat: scheme.bearerFormat } : {}),
+                            },
+                        },
+                        summary: scheme.bearerFormat ? `HTTP bearer (${scheme.bearerFormat})` : 'HTTP bearer',
+                    };
+                }
+                if (scheme.scheme === 'basic') {
+                    return {
+                        ok: true,
+                        prefill: { type: 'http', http: { scheme: 'basic' } },
+                        summary: 'HTTP basic',
+                    };
+                }
+                // MCPHub's form can select digest but applySecurityToClient() never
+                // emits a
+                // Digest header, so declaring it as prefilled would silently mislead.
+                return {
+                    ok: false,
+                    summary: `HTTP ${scheme.scheme}`,
+                    unsupportedReason: `HTTP scheme '${scheme.scheme}' cannot be sent by MCPHub.`,
+                };
+            case 'apiKey': {
+                const location = scheme.in;
+                if (location === 'header' || location === 'query' || location === 'cookie') {
+                    return {
+                        ok: true,
+                        prefill: { type: 'apiKey', apiKey: { name: scheme.name, in: location } },
+                        summary: `API key in ${location} '${scheme.name}'`,
+                        cookieHint: location === 'cookie',
+                    };
+                }
+                return {
+                    ok: false,
+                    summary: `API key in '${location}'`,
+                    unsupportedReason: `API key location '${location}' is not supported by MCPHub.`,
+                };
+            }
+            case 'oauth2': {
+                // Only flows with a token endpoint are actionable for MCPHub's
+                // client-credentials token fetch; prefill it when the spec provides it.
+                const tokenUrl = scheme.flows?.clientCredentials?.tokenUrl ||
+                    scheme.flows?.password?.tokenUrl ||
+                    scheme.flows?.authorizationCode?.tokenUrl;
+                return {
+                    ok: true,
+                    prefill: {
+                        type: 'oauth2',
+                        ...(tokenUrl ? { oauth2: { tokenUrl } } : {}),
+                    },
+                    summary: 'OAuth2',
+                };
+            }
+            case 'openIdConnect':
+                return {
+                    ok: true,
+                    prefill: { type: 'openIdConnect', openIdConnect: { url: scheme.openIdConnectUrl } },
+                    summary: 'OpenID Connect',
+                };
+            default:
+                return {
+                    ok: false,
+                    summary: `security scheme '${schemeName}'`,
+                    unsupportedReason: `Security scheme type '${scheme.type}' is not supported by MCPHub.`,
+                };
+        }
+    }
     isCookieSessionEnabled(sessionId) {
         return (!!this.config.openapi?.cookieSession && typeof sessionId === 'string' && sessionId.length > 0);
     }