aiquila-mcp 0.3.29 → 0.3.30

package/dist/auth/provider.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 import { createHash, timingSafeEqual } from 'node:crypto';
 import { SignJWT, jwtVerify } from 'jose';
-import { InvalidGrantError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import { InvalidGrantError, InvalidTokenError, } from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import { ClientsStore, CodeStore, RefreshStore } from './store.js';
 import { logger } from '../logger.js';
 // --- JWT helpers (HMAC-SHA256 via jose) ---
@@ -196,7 +196,10 @@ export class NextcloudOAuthProvider {
         const claims = await verifyJwt(token, this.getSecret(), issuer ? { issuer, audience: new URL('/mcp', issuer).toString() } : undefined);
         if (!claims) {
             logger.warn('[auth] Access token verification failed: invalid or expired token');
-            throw new Error('Invalid or expired access token');
+            // InvalidTokenError (not a bare Error) so the SDK answers 401 with a
+            // WWW-Authenticate challenge. A bare Error becomes a 500, and clients
+            // treat that as a server fault rather than a cue to re-authenticate.
+            throw new InvalidTokenError('Invalid or expired access token');
         }
         return {
             token,

package/dist/transports/http.js

@@ -9,10 +9,16 @@ import { createServer, SERVER_VERSION } from '../server.js';
 import { NextcloudOAuthProvider } from '../auth/provider.js';
 import { probeStateDir, StateDirNotWritableError, stateUnwritableMessage, markStateUnwritableWarned, } from '../auth/store.js';
 import { loginHandler } from '../auth/login.js';
+import { isPublicRequest } from './lazy-auth.js';
 import { logger } from '../logger.js';
 import { fetchStatus } from '../client/ocs.js';
 const DEFAULT_PORT = 3339;
 const MCP_PATH = '/mcp';
+const SCOPES_SUPPORTED = ['mcp:tools', 'mcp:resources', 'mcp:prompts'];
+// Scope advertised in the WWW-Authenticate challenge. Clients request exactly
+// this on authorisation; omitting it makes them fall back to the full
+// `scopes_supported` union, which produces an over-broad consent prompt.
+const CHALLENGE_SCOPE = 'mcp:tools';
 // TLS error codes that indicate a self-signed or untrusted certificate.
 // Network errors (ECONNREFUSED, ETIMEDOUT) are not included — they mean the
 // proxy is not yet reachable, which is transient and should not log a warning.
@@ -81,6 +87,10 @@ export async function startHttp() {
     const port = parseInt(process.env.MCP_PORT || String(DEFAULT_PORT), 10);
     const host = process.env.MCP_HOST || '0.0.0.0';
     const authEnabled = process.env.MCP_AUTH_ENABLED === 'true';
+    // Lazy authentication is on by default: clients need to inspect a connector
+    // before signing in. Operators who treat /mcp as a fully closed endpoint can
+    // set MCP_LAZY_AUTH=false to require a bearer token on every JSON-RPC method.
+    const lazyAuthEnabled = process.env.MCP_LAZY_AUTH !== 'false';
     if (!authEnabled) {
         if (process.env.MCP_ALLOW_UNAUTHENTICATED !== 'true') {
             throw new Error('HTTP transport requires MCP_AUTH_ENABLED=true. ' +
@@ -220,7 +230,7 @@ export async function startHttp() {
             issuerUrl: new URL(issuerUrl),
             resourceServerUrl: new URL(MCP_PATH, issuerUrl),
             serviceDocumentationUrl: new URL('https://github.com/elgorro/aiquila'),
-            scopesSupported: ['mcp:tools', 'mcp:resources', 'mcp:prompts'],
+            scopesSupported: SCOPES_SUPPORTED,
         }));
         // Fallback: serve protected resource metadata at the root well-known path too,
         // so clients that use the server root URL (without /mcp) can discover the resource.
@@ -229,7 +239,7 @@ export async function startHttp() {
             res.json({
                 resource: new URL(MCP_PATH, issuerUrl).href,
                 authorization_servers: [issuerUrl],
-                scopes_supported: ['mcp:tools', 'mcp:resources', 'mcp:prompts'],
+                scopes_supported: SCOPES_SUPPORTED,
                 resource_documentation: 'https://github.com/elgorro/aiquila',
             });
         });
@@ -265,9 +275,44 @@ export async function startHttp() {
                         logger.warn({ status: res.statusCode, rpcMethod: req.body?.method }, '[mcp] Request rejected');
                     }
                 });
+                // The SDK appends `scope="..."` to the challenge only when
+                // `requiredScopes` is set — but setting that would also *enforce* the
+                // scope, and 403 every token issued before scopes were requested (plus
+                // the internal service token, which carries none). Advertise the scope
+                // without enforcing it by decorating the header on its way out.
+                const setHeader = res.setHeader.bind(res);
+                res.setHeader = (name, value) => {
+                    if (typeof name === 'string' &&
+                        name.toLowerCase() === 'www-authenticate' &&
+                        typeof value === 'string' &&
+                        !value.includes('scope=')) {
+                        value = `${value}, scope="${CHALLENGE_SCOPE}"`;
+                    }
+                    return setHeader(name, value);
+                };
                 next();
             },
-            requireBearerAuth({ verifier: provider }),
+            // Lazy-auth gate: the handshake, capability listings, and public tools are
+            // served anonymously so clients can inspect the connector before sign-in.
+            // Everything else falls through to requireBearerAuth below.
+            // Omitted entirely when MCP_LAZY_AUTH=false, restoring a chain in which
+            // every JSON-RPC method requires a bearer token.
+            ...(lazyAuthEnabled
+                ? [
+                    async (req, res, next) => {
+                        if (!req.headers.authorization && isPublicRequest(req.body)) {
+                            logger.debug({ rpcMethod: req.body?.method }, '[mcp] Public request (unauthenticated)');
+                            await handleMcpRequest(req, res);
+                            return;
+                        }
+                        next();
+                    },
+                ]
+                : []),
+            requireBearerAuth({
+                verifier: provider,
+                resourceMetadataUrl: new URL('/.well-known/oauth-protected-resource/mcp', issuerUrl).href,
+            }),
             async (req, res) => {
                 logger.debug({ method: req.method, rpcMethod: req.body?.method }, '[mcp] Request received');
                 await handleMcpRequest(req, res);
@@ -288,6 +333,9 @@ export async function startHttp() {
         if (authEnabled) {
             const tp = process.env.MCP_TRUST_PROXY;
             logger.info({ issuer: process.env.MCP_AUTH_ISSUER }, 'OAuth 2.0 authentication enabled');
+            logger.info({ lazyAuth: lazyAuthEnabled }, lazyAuthEnabled
+                ? 'Lazy auth enabled — tools/list and public tools are readable without a token (set MCP_LAZY_AUTH=false to require one)'
+                : 'Lazy auth disabled — every JSON-RPC method requires a bearer token');
             logger.info({ trustProxy: tp && tp !== 'false' ? tp : 'disabled' }, 'Trust proxy setting (set MCP_TRUST_PROXY=1 if behind a reverse proxy)');
             if (hasStaticClient) {
                 logger.info({ clientId: process.env.MCP_CLIENT_ID }, 'Static OAuth client configured');

package/dist/transports/lazy-auth.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Lazy authentication (mixed auth) for the Streamable HTTP transport.
+ *
+ * Unauthenticated clients may complete the MCP handshake, enumerate the server's
+ * capabilities, and call the tools listed in PUBLIC_TOOLS.  Anything else is
+ * refused at the HTTP layer with a 401 + WWW-Authenticate challenge, which is
+ * what makes clients render an inline "Connect" card and retry the same call
+ * once the user has authorised.
+ *
+ * The refusal has to be an HTTP status, so the check must run *before* the
+ * JSON-RPC message reaches the MCP SDK: once a tool handler is executing, its
+ * return value is already destined to be wrapped in a 200 response, and a 200
+ * carrying `isError: true` reads as an application-level failure, not an auth
+ * challenge.
+ *
+ * @see https://claude.com/docs/connectors/building/lazy-authentication
+ */
+/**
+ * JSON-RPC methods reachable without a token.  These describe the server rather
+ * than touching the Nextcloud instance behind it, so they leak nothing.
+ */
+const PUBLIC_METHODS = new Set([
+    'initialize',
+    'notifications/initialized',
+    'notifications/cancelled',
+    'ping',
+    'tools/list',
+    'resources/list',
+    'resources/templates/list',
+    'prompts/list',
+]);
+/**
+ * Tools reachable without a token.  Every other AIquila tool proxies to
+ * Nextcloud, so this set is deliberately tiny.
+ */
+const PUBLIC_TOOLS = new Set(['get_local_time']);
+function isPublicMessage(msg) {
+    if (!msg || typeof msg !== 'object')
+        return false;
+    const method = msg.method;
+    if (typeof method !== 'string')
+        return false;
+    if (method === 'tools/call') {
+        const name = msg.params?.name;
+        return typeof name === 'string' && PUBLIC_TOOLS.has(name);
+    }
+    return PUBLIC_METHODS.has(method);
+}
+/**
+ * True when every message in the request body is safe to serve anonymously.
+ *
+ * A JSON-RPC batch is a single HTTP request and therefore gets a single status
+ * code, so one protected message taints the whole batch.  An empty or
+ * non-JSON-RPC body (a GET for the SSE stream, a DELETE to end a session) is
+ * never public — those still require a bearer token.
+ */
+export function isPublicRequest(body) {
+    const messages = Array.isArray(body) ? body : [body];
+    if (messages.length === 0)
+        return false;
+    return messages.every(isPublicMessage);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiquila-mcp",
-  "version": "0.3.29",
+  "version": "0.3.30",
   "description": "Nextcloud MCP server — files, calendar, contacts, mail, maps, notes, tasks & 120+ more tools",
   "type": "module",
   "main": "dist/index.js",